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说 明 

本 教程 翻译 自 Miguel Grinberg 的 blog 的 2017 年 新 版 The Flask Mega-Tutorial 教 程 ， 以 供 英语 
能 力 较 弱 的 开发 人 员 参 考 。 感 谢 Miguel Grinberg ! 

全 部 二 十 三 章 都 已 完成 翻译 ， 如 果 有 任何 版 权 问 题 ， 请 联系 luhuisicnu@163.com ° 


如 果 有 任何 技术 疑问 ， 欢迎 加 入 QQ 群 (484327418) 讨论 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part |: Hello, World! 


B > 跟随 它 你 将 学 会 用 Python 和 Flask 来 创建 Web 应 用 。 上 面 的 视 
频 包 含 了 整个 教程 的 内 容 预 览 〈 译 者 注 : 视频 见 原文 ) 。 通 过 学 习 本 章 内 容 ， 你 将 学 会 如 何 
a a 


教程 中 所 有 的 代码 示例 都 托管 在 GitHub 上 。 虽 然 直 接 从 GitHub 下 载 代码 可 以 节省 写 代码 的 步 
骤 ， 但 是 我 强烈 建议 你 至 少 在 前 几 章 自己 动手 书写 这 些 代 码 。 一 旦 你 熟悉 了 Flask 和 示例 应 
用 ， 一 些 繁琐 重复 的 代码 就 可 以 直接 从 GitHub 复 制 了 。 


在 每 章 的 开头 ， 我 都 将 提供 三 个 GitHub 的 链接 来 帮助 你 顺畅 地 学 习 本 章 的 内 容 。 点 击 Browse 
链接 会 打开 GitHub 上 Microblog 项 目 在 本 章 的 对 应 代码 库 页 面 ， 不 会 包含 之 后 章节 的 任何 新 增 
代码 。 而 Zip 链 接 则 提供 了 这 份 代码 库 的 zip 打 包 文 件 的 下 载 地 址 。 如 果 点 击 Diff 链 接 ， 打 开 的 
将 会 是 本 章节 的 代码 变更 信息 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


安装 Python 


oe baa etna A | 立马 安装 吧 。 如 果 操 作 系统 默认 没有 提供 Python 安 

， 可 以 从 Python 官方 网 站 下 载 。 如 果 你 使 用 Microsoft Windows 操 作 系 统 并 且 打 算 使 用 
We ， 需 要 注意 ， 不 要 在 上 面 使 用 Windows 版 本 的 Python， 而 要 使 用 类 Unix 版 
本 ， 比 如 从 Ubuntu 获取 〈 对 应 WSL ) 或 从 Cygwin 上 获取 。 


为 了 验证 Python 是 否 正确 安装 ， 你 可 以 打开 一 个 终端 窗口 并 输入 pythons (如 果 不 存 在 这 个 
命令 ， 那 就 输入 python ) 。 预 期 的 输出 如 下 : 


$ python3 

Python 3.5.2 (default, Nov 17 2016, 17:05:23) 

[GCC 5.4.0 20160609] on linux 

Type "help", "copyright", "credits" or "license" for more information. 
>>> 


Python 解 释 器 中 ， 光 标 不 断 闪 烁 ， 等 待 着 你 输入 Python 语 句 。 在 未 来 的 章节 中 ， 你 可 以 充分 
体会 到 交互 式 解释 器 的 魅力 。 至 少 现在 它 能 够 帮 你 确认 Python 已 经 成 功 安装 的 事实 。 可 以 输 
入 exit() 并 回 车 来 退出 交互 式 解释 器 。 在 Linux 和 Mac OS 系统 上 ， 按 下 快捷 键 Ctrl-D 
也 可 以 快速 退出 交互 式 解 释 器 。 在 Windows 操 作 系 统 上 ， 则 是 通过 按 下 Ctrl-Z 后 跟 上 Enter 快 
捷 键 来 快速 退出 。 


安装 Flask 


下 一 步 开 始 安装 Flask， 在 这 之 前 我 要 告诉 你 安装 Python 三 方 包 的 最 佳 实践 。 


Python 将 所 有 三 方 包 托 管 到 一 个 公共 仓库 ， 任 何人 都 能 从 这 个 公共 仓库 下 载 并 安装 所 有 的 三 
方 包 。Python 将 三 方 包公 共 仓 库 命名 为 PyPIl 以 表示 Python Package Index 的 缩写 (被 一 些 人 戏 
称 为 "cheese shop")。 从 PyPl 上 安装 三 方 包 非常 简单 ，Python 专 门 提供 了 一 个 名 为 pip HL 
具 来 解决 这 个 问题 (Python2.7 中 不 含 pip 工具 ， 需 要 单独 安装 ) 。 


安装 三 方 包 时 ， 使 用 pip 命令 如 下 : 


$ pip install <package-name> 


有 趣 的 是 ， 这 个 方法 在 大 多 数 情 况 下 不 适用 。 假 如 Python 解释 器 是 全 局 安装 的 ， 所 有 用 户 都 
能 使 用 ， 那 么 普通 用 户 则 没有 权限 来 修改 它 ， 因 此 只 能 用 管理 员 账 户 来 执行 安装 操作 。 即 使 
忽略 操作 的 复杂 性 ， 使 用 这 种 全 局 安装 的 方式 会 发 生 什么 ?了 pip 工具 从 PyPI 上 下 载 三 方 包 并 
安装 到 全 局 Python 目录 下 ， 即 刻 起 ， 所 有 Python 脚本 都 可 以 访问 到 这 个 三 方 包 。 想 象 这 样 一 
个 场景 ， 你 之 前 用 当时 的 最 新 版 本 Flask 一 一 0.11 版 本 的 Flask 开 发 了 一 个 Web 应 用 ， 现 在 
Flask 已 经 更 新 到 了 0.12 版 本 ， 你 想 要 使 用 0.12 版 本 的 Flask 开 发 第 二 个 Web 应 用 。 但 是 ， 如 果 
将 Flask 从 0.11 版 本 升级 到 0.12 版 本 可 能 会 导致 第 一 个 Web 应 用 出 现 故障 。 解 决 这 个 问题 的 方 
法 最 好 不 过 为 日 Web 应 用 安装 和 使 用 Flask0.11 版 本 ， 为 新 Web 应 用 安装 和 使 用 Flask0.12 版 
本 。 


为 了 解决 维护 不 同 应 用 程序 对 应 不 同 版 本 的 问题 ，Python 使 用 了 虚拟 环境 的 概念 。 虚拟 环境 
是 Python 解释 器 的 完整 副本 。 在 虚拟 环境 中 安装 三 方 包 时 只 会 作用 到 虚拟 环境 ， 全 局 Python 
解释 器 不 受 影 响 。 那么 ， 就 为 每 个 应 用 程序 安装 各 自 的 虚拟 环境 吧 。 虚拟 环境 还 有 一 个 好 
处 ， 即 它们 由 创建 它们 的 用 户 所 拥有 ， 所 以 不 需要 管理 员 帐 户 。 


我 们 先 创建 项 目 目 录 ， 我 将 这 个 应 用 命名 为 microblog : 


$ mkdir microblog 
$ cd microblog 


如 果 你 正在 使 用 Python3， 虚 拟 环境 已 经 成 为 内 置 模块 ， 可 以 直接 通过 如 下 命令 来 创建 它 : 


$ python3 -m venv venv 


译 者 注 : 这 个 命令 不 一 定 能 够 执行 成 功 ， 比 如 译 者 在 Ubuntu16.04 环 境 下 执行 ， 提 示 需 要 


先 安装 对 应 的 依赖 。 sudo apt-get install python3-venv 


使 用 这 个 命令 来 让 Python 运行 venv 包 ， 它 会 创建 一 个 名 为 ven 的 虚拟 环境 。 命令 中 的 第 一 
个 “venv" 是 Python 虚拟 环境 包 的 名 称 ， 第 二 个 是 要 用 于 这 个 特定 环境 的 虚拟 环境 名 称 。 如 果 
你 觉得 这 样 很 混乱 ， 可 以 用 你 自 定 义 的 虚拟 环境 名 字 替 换 第 二 个 venv 。 我 习惯 在 项 目 目录 中 
创建 了 名 为 venv 的 虚拟 环境 ， 所 以 无 论 何 时 cd 到 一 个 项 目 中 ， 都 会 找到 相应 的 虚拟 环境 。 


请 注意 ， 在 一 些 操作 系统 中 ， 你 可 能 需要 在 上 面 的 命令 中 使 用 python 而 不 是 python3 。 一些 
安装 规范 对 Python 2.x 版 本 使 用 python ， 对 3.x 版 本 使 用 pythons ， 而 另 一 些 则 将 python BR 
射 到 3.x 版 本 。 


命令 执行 完成 后 ， 当 前 目录 下 就 会 新 增 一 个 名 为 veny 的 目录 来 存储 这 个 虚拟 环境 的 相关 文 
件 。 


如 果 你 使 用 的 Python 版 本 低 于 3.4 (包括 2.7 版 本 ) ， 则 不 会 默认 支持 虚拟 环境 。 对 于 这 些 版 
本 的 Python， 在 创建 虚拟 环境 之 前 ， 需 要 下 载 并 安装 称 为 virtualenv 的 第 三 方 工具 。 一 旦 安装 
了 virtualenv， 你 可 以 使 用 以 下 命令 创建 一 个 虚拟 环境 : 


$ virtualenv venv 


不 管 你 用 什么 方法 创建 虚拟 环境 ， 创 建 完毕 之 后 还 需要 激活 才能 够 进入 这 个 诬 拟 环境 。 要 激 
活 你 的 全 新 虚拟 环境 ， 需 使 用 以 下 命令 : 


$ source venv/bin/activate 
(venv) $ _ 


如 果 你 使 用 的 是 Microsoft Windows 命 令 提 示 符 窗口 ， 则 激活 命令 稍 有 不 同 : 


$ venv\Scripts\activate 
(venv) $ _ 


激活 一 个 虚拟 环境 ， 终 端 会 话 的 环境 配置 就 会 被 修改 ， 之 后 你 键入 python 的 时 候 ， 实 际 上 是 
调用 的 虚拟 环境 中 的 Python 解 释 器 。 此 外 ， 终 端 提 示 符 也 被 修改 成 包含 被 激活 的 诬 拟 环境 的 
名 称 的 格式 。 这 种 激活 是 临时 的 和 私有 的 ， 因 此 在 关闭 终端 窗口 时 它们 将 不 会 保留 ， 也 不 会 
影响 其 他 的 会 话 。 那么 ， 当 你 需要 同时 打开 多 个 终端 窗口 来 调试 不 同 的 应 用 时 ， 每 个 终端 窗 
口 都 可 以 激活 不 同 的 虚拟 环境 而 不 会 相互 影响 。 


成 功 创建 和 激活 了 虚拟 环境 之 后 ， 你 可 以 安装 Flask 了 ， 命 令 如 下 : 


(venv) $ pip install flask 


想 要 验证 安装 是 否 成 功 ， 可 以 打开 Python 解释 器 ， 并 用 1jmpot 语 名 来 导入 它 : 


>>> import flask 
SS 


如 果 语 名 没有 报错 ， 那 么 茶 喜 你 ，Flask 安 装 成 功 了 | 


"Hello, World" Flask 应 用 


Flask 网 站 展示 了 一 个 仅 有 五 行 代码 的 简单 示例 应 用 程序 。 而 我 会 告诉 你 一 个 稍微 更 复杂 的 例 
子 ， 它 将 为 你 编写 更 大 的 应 用 程序 提供 一 个 很 好 的 基础 结构 。 


应 用 程序 是 存在 于 包 中 的 。 在 Python 中 ， 包 含 jinit .py 文件 的 子 目 录 被 视 为 一 个 可 导入 的 包 
当 你 导入 一 个 包 时 ， init .py 会 执行 并 定义 这 个 包 类 露 给 外 界 的 属性 。 


那 就 创建 一 个 名 为 app 的 包 来 存放 整个 应 用 吧 。 记 得 切换 到 Imicroblog 目 录 下 ， 并 执行 如 下 命 


a; 


(venv) $ mkdir app 


并 在 其 下 创建 文件 _init .py ， 输 入 如 下 的 代码 : 


from flask import Flask 
app = Flask(__name_) 


from app import routes 


上 面 的 脚本 仅仅 是 从 flask 中 导入 的 类 Flask ， 并 以 此 类 创建 了 一 个 应 用 程序 对 象 。 传递 

给 Flask 类 的 _ name 变量 是 一 个 Python 预定 义 的 变量 ， 它 表示 当前 调用 它 的 模块 的 名 字 。 
当 需 要 加 载 相关 的 资源 ， 如 我 将 在 第 二 草 讲 到 的 模板 文件 ，Flask 就 使 用 这 个 位 置 作为 起 点 来 
计算 绝对 路 径 。 代码 的 最 后 ， 应 用 程序 导入 尚未 存在 的 routes 模块 。 


这 段 代码 ， 乍 一 看 可 能 会 让 人 迷 


其 一 ， 这 里 有 两 个 实体 名 为 app ° app 包 由 app 目 录 和 init .py 脚本 来 定义 构成 ， 并 
在 from app import routes 语 名 中 被 引用 。 app 变量 被 定义 为 jinit .py 脚本 中 的 Flask 类 的 一 
个 实例 ， 以 至 于 它 成 为 app 包 的 属性 。 


其 二 ， routes 模块 是 在 底部 导入 的 ， 而 不 是 在 脚本 的 顶部 。 最 下 面 的 导入 是 解决 循环 导入 的 
问题 ， 这 是 Flask 应 用 程序 的 常见 问题 。 你 将 会 看 到 routes 模块 需要 导入 在 这 个 脚本 中 定义 
的 app 变量 ， 因 此 将 routes 的 导入 放 在 底部 可 以 避免 由 于 这 两 个 文件 之 间 的 相互 引用 而 导致 
的 错误 。 


ZÆ routes 模块 中 有 些 什 么 ? 路 由 是 应 用 程序 实现 的 不 同 URL 。 在 Flask 中 ， 应 用 程序 路 
由 的 处 理 逻辑 被 编写 为 Python 函数 ， 称 为 视图 函数 。 视 图 函数 被 映射 到 一 个 或 多 个 路 由 
URL， 以 便 Flask 知 道 当 客 户 端 请 求 给 定 的 URL 时 执行 什么 逻辑 。 


这 是 需要 写 入 到 app/routes.py 中 的 第 一 个 视图 函数 的 代码 : 


from app import app 


@app.route('/') 
@app.route('/index' ) 
def index(): 

return "Hello, World!" 


这 个 视图 函数 简单 到 只 返回 一 个 字符 串 作 为 问候 用 语 。 函数 上 面 的 两 个 奇怪 

的 @app.route 行 是 装饰 器 ， 这 是 Python 语言 的 一 个 独特 功能 。 装饰 器 会 修改 跟 在 其 后 的 函 
数 。 装 饰 器 的 常见 模式 是 使 用 它们 将 隐 数 注册 为 某 些 事件 的 回调 防 数 。 在 这 种 情况 

TF? @app.route 修饰 器 在 作为 参数 给 出 的 URL 和 函数 之 间 创 建 一 个 关联 。 在 这 个 例子 中 ， 
有 两 个 装饰 器 ， 它 们 将 URL / 和 /index 索引 关联 到 这 个 函数 。 这 意味 着 ， 当 Web 浏 览 器 请 
求 这 两 个 URL 中 的 任何 一 个 时 ，Flask 将 调用 该 函数 并 将 其 返回 值 作 为 响应 传递 回 浏览 器 。 这 
样 做 是 为 了 在 运行 这 个 应 用 程序 的 时 候 会 稍微 有 一 点 点 意义 。 


要 完成 应 用 程序 ， 你 需要 在 定义 Flask 应 用 程序 实例 的 顶层 〈 译 者 注 : 也 就 是 microblog 目 录 
下 ) 创建 一 个 命名 为 microblog.py 的 Python 脚 本 。 它 仅 拥有 一 个 导入 应 用 程序 实例 的 行 : 


from app import app 


还 记得 两 个 ap FAG? 在 这 里 ， 你 可 以 在 同一 句 话 中 看 到 两 者 。Flask 应 用 程序 实例 被 称 
A app °? Æ app 包 的 成 员 。 from app import app 语句 从 app 包 导 入 其 成 员 app XE ° 如 果 
你 觉得 这 很 混乱 ， 你 可 以 重 命名 包 或 者 变量 。 


只 要 确保 所 做 的 操作 完全 正确 ， 那 么 你 就 可 以 看 到 如 下 面 的 项 目 结构 图 : 


microblog/ 
venv/ 


app/ 
__init__.py 
routes.py 

microblog.py 


不 管 你 信 不 信 ， 这 个 应 用 的 第 一 个 版 本 现在 完成 了 ! 但 是 在 运行 之 前 ， 需 要 通过 设 
置 FLASK_APP 环境 变量 告诉 Flask 如 何 导 入 它 : 


(venv) $ export FLASK_APP=microblog.py 


如 果 你 使 用 Microsoft Windows 操 作 系 统 ， 在 上 面 的 命令 中 使 用 set 替换 export ° 


万 事 俱 备 ， 只 欠 东 风 | 运行 如 下 命令 来 运行 你 的 第 一 个 Web 应 用 吧 : 


(venv) $ flask run 
* Serving Flask app "microblog" 
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 


服务 局 动 后 将 处 于 阻塞 监听 状态 > 将 等 待 客户 端 连接 ° flask run 的 输出 表明 服务 器 正在 运 
行 在 IP 地 址 127.0.0.1 上 ， 这 是 本 机 的 回环 IP 地 址 。 这 个 地 址 很 常见 ， 并 有 一 个 更 简单 的 名 
字 ， 你 可 能 已 经 看 过 : localhost? 网络 服务 器 监听 在 指定 端口 号 等 待 连接 。 部 署 在 生产 Web 
服务 器 上 的 应 用 程序 通常 会 在 端口 443 上 进行 监听 ， 如 果 不 执行 加 密 ， 则 有 时 会 监听 80， 但 局 
用 这 些 端口 需要 root 权 限 。 由 于 此 应 用 程序 在 开发 环境 中 运行 ， 因 此 Flask 使 用 自由 端口 
5000。 现在 打开 您 的 网 络 浏览 器 并 在 地 址 栏 中 输入 以 下 URL : 


http://localhost :5000/ 


或 者 ， 你 也 可 以 使 用 另 一 个 URL : 


http://localhost :5000/index 


应 用 程序 路 由 映射 执行 了 吗 ? 第 一 个 URL 映 射 到 / ， 而 第 二 个 映射 到 / index 。 这 两 个 路 


由 都 与 应 用 程序 中 唯一 的 视图 郊 数 相关 联 ， 所 以 它们 产生 相同 的 输出 ， 即 部 数 返 回 的 字符 
Po 如 果 你 输入 任何 其 他 网 址 ， 则 会 出 现 错误 ， 因 为 只 有 这 两 个 URL 被 应 用 程序 识别 。 


i localhost:5000/index 
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Hello, World! 





完成 演示 之 后 ， 你 可 以 按 下 Ctrl-C 来 停止 Web 服 务 


监 是 可 喜 可 贺 ! 你 已 经 成 功 地 向 成 为 一 名 Web 开 发 者 的 道路 上 到 出 了 重要 的 第 一 步 ! 


本 文 翻 译 自 The Flask Mega-Tutorial Part Il: Templates 
Æ Flask Mega-Tutorial 系 列 的 第 二 部 分 中 ， 我 将 讨论 如 何 使 用 模板 。 


学 习 完 第 一 章 之 后 ， 你 已 经 拥有 了 一 个 虽然 简单 ， 但 是 可 以 成 功 运行 Web 应 用 ， 它 的 文件 结 
构 如 下 : 


microblog\ 
venv\ 
app\ 
__init__.py 
routes.py 
microblog.py 


在 终端 会 话 中 设置 环境 变量 FLASK_APP=microblog.py ， 然 后 执行 flask run 命令 来 运行 应 用 。 
包含 这 个 应 用 的 Web 服 务 启 动 之 后 ， 你 可 以 通过 在 Web 浏 览 器 的 地 址 栏 中 键 
入 http:Nlocalhost:5000/ URL 来 验证 。 


本 章 将 沿用 这 个 应 用 ， 在 此 之 上 ， 你 将 学 习 如 何 生 成 包含 复杂 结构 和 诸多 动态 组 件 的 网 页 。 
如 果 对 这 个 应 用 和 相关 开发 流程 有 所 遗忘 ， 请 回顾 第 一 章 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


什么 是 模板 ? 


我 设计 的 微 博 应 用 程序 的 主页 会 有 一 个 欢迎 用 户 的 标题 。 虽 然 目 前 的 应 用 程序 还 没有 实现 用 
户 概念 ， 但 这 不 妨碍 我 使 用 一 个 Python 字 典 来 模拟 一 个 用 户 ， 如 下 所 示 : 


user = {'username': 'Miguel'} 


创建 模拟 对 象 是 一 项 实用 的 技术 ， 它 可 以 让 你 专注 于 应 用 程序 的 一 部 分 ， 而 无 需 为 系统 中 尚 
不 存在 的 其 他 部 分 分 心 。 在 设计 应 用 程序 主页 的 时 候 ， 我 可 不 希望 因为 没有 一 个 用 户 系统 来 
分 散 我 的 注意 力 ， 因 此 我 使 用 了 模拟 用 户 对 象 ， 来 继续 接 下 来 的 工作 。 


原先 的 视图 部 数 返回 简单 的 字符 囊 ， 我 现在 要 将 其 扩展 为 包含 完整 HTML 页 面 元 素 的 字符 囊 ， 
如 下 所 示 : 


from app import app 


@app.route('/') 
@app.route('/index' ) 
def index(): 
user = {'username': 'miguel'} 
return ''' 
<html> 
<head> 
<title>Home Page - Microblog</title> 
</head> 
<body> 
<hi>Hello, ''' + user['username'] + '''!</hi> 
</body> 
</html>''' 


对 HTML 标 记 语 言 不 熟悉 的 话 ， 建 议 阅读 一 下 Wikipedia 上 的 简介 HTML Markup 


利用 上 述 的 代码 更 新 这 个 视图 函数 ， 然 后 再 次 在 浏览 器 打开 它 的 URL 看 看 结果 


四 Home Page - Microblog 
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Hello, Miguel! 





如 果 我 说 这 个 函数 返回 HTML 的 方式 并 不 友好 的 话 ， 你 可 能 会 觉得 证 异 。 设 想 一 下 ， 当 这 个 视 
图 函数 中 的 用 户 和 博客 不 断 变 化 时 ， 里 面 的 代码 将 会 变 得 多 么 的 复杂 。 应 用 的 视图 函数 及 其 
关联 的 URL 也 会 持续 增长 。 如 果 哪 天 我 决定 更 改 这 个 应 用 的 布局 ， 那 就 不 得 不 更 新 每 个 视图 
函数 的 HTML 字 符 囊 。 显 然 ， 随 着 应 用 的 扩张 ， 这 种 方式 完全 不 可 行 。 


将 应 用 程序 的 后 台 逻 辑 和 网 页 布局 划分 开 来 ， hii 不 觉得 更 容易 组 织 管理 吗 ? 甚至 你 可 以 聘请 
一 位 Web 设 计 师 来 设计 一 个 杀手 级 的 网 站 前 端 ， 而 你 只 需要 用 Python 编写 后 台 应 用 逮 辑 。 


模板 有 助 于 实现 页 面 展现 和 业务 逻辑 之 间 的 分 离 。 在 Flask 中 ， 模 板 被 编写 为 单独 的 文件 ， 存 
储 在 应 用 程序 包 内 的 templates 文 件 夹 中 。 在 确定 你 在 microblog 目 录 后 ， 创 建 一 个 存储 模板 
的 目录 : 


(venv) $ mkdir app/templates 


在 下 面 可 以 看 到 你 的 第 一 个 模板 ， 它 的 功能 与 上 面 的 index() 视图 函数 返回 的 HTML 页 面相 
似 。 把 这 个 文件 写 在 app/templates/index.html 中 : 


<html> 
<head> 
<title>{{ title }} - Microblog</title> 
</head> 
<body> 
<hi>Hello, {{ user.username }}!</h1> 
</body> 
</html> 


这 个 HTML 页 面 看 起 来 非常 简单 ， 唯 一 值得 关注 的 地 方 是 {{ ... Ho {{ ... p 包含 的 内 容 
是 动态 的 ， 只 有 在 运行 时 才 知 道具 体 表示 成 什么 样子 。 
网 


页 泻 染 转移 到 HTML 模 板 之 后 ， 视 图 函数 就 能 被 简化 : 


from flask import render_template 
from app import app 


@app.route('/') 
@app.route('/index' ) 
def index(): 
user = {'username': 'Miguel'} 
return render_template('index.html', title='Home', user=user) 


看 起 来 好 多 了 吧 ? 赶紧 试 试 这 个 新 版 本 的 应 用 程序 ， 看 看 模板 是 如 何 工作 的 。 在 浏览 器 中 加 
载 页 面 后 ， 你 需要 从 浏览 器 查看 HTML 源 代码 并 将 其 与 原始 模板 进行 比较 。 


将 模板 转换 为 完整 的 HTML 页 面 的 操作 称 为 泻 染 。 为 了 泻 染 模板 ， 需 要 从 Flask 框 架 中 导入 一 
个 名 为 render_template() 的 函数 。 该 函数 需要 传 入 模板 文件 名 和 模板 参数 的 变量 列表 ， 并 返 
回 模板 中 所 有 占 位 符 都 用 实际 变量 值 替换 后 的 字符 串 结 果 。 


render_template() 函数 调用 Flask 框 架 原生 依赖 的 Jinja2 模 板 引 营 。 Jinja2 
用 render_template() 函数 传 入 的 参数 中 的 相应 值 替换 {{...}} 块 。 


条 件 语句 


在 泻 染 过 程 中 使 用 实际 值 替换 占 位 符 ， 只 是 Jinja2 在 模板 文件 中 支持 的 诸多 强大 操作 之 一 。 模 
板 也 支持 在 {%...%} 块 内 使 用 控制 语句 。 jndex.html 模 板 的 下 一 个 版 本 添加 了 一 个 条 件 语 
ay: 


<html> 
<head> 
{% if title %} 
<title>{{ title }} - Microblog</title> 
{% else %} 
<title>welcome to Microblog!</title> 
{% endif %} 


</head> 
<body> 
<hi>Hello, {{ user.username }}!</h1> 
</body> 
</html> 
IE > RARA RILT > PRAIA AASTA R RASSA title 的 关键 字 参 


数 ， 那 么 ee, 而 不 是 显示 一 个 空 的 标题 。 你 可 以 通过 在 视图 函数 
的 render_template() 调用 中 去 除 title 参数 来 试 试 这 个 条 件 语句 是 如 何 生 效 的 。 


循环 


登录 后 的 用 户 可 能 想 要 在 主页 上 查看 其 他 用 户 的 最 新 动态 ， 针 对 这 个 需求 ， 我 现在 要 做 的 是 
丰富 这 个 应 用 来 满足 它 


x 
我 将 会 故 技 重 施 ， 使 用 模拟 对 象 的 把 戏 来 创建 一 些 模拟 用 户 和 动态 : 


from flask import render_template 
from app import app 


@app.route('/') 
@app.route('/index') 
def index(): 


user = {'username': 'Miguel'} 
posts = [ 
{ 
‘author': {'username': 'John'}, 
'body': ‘Beautiful day in Portland!' 
}, 
{ 
‘author': {'username': 'Susan'}, 
"pody': 'The Avengers movie was so cool!' 
} 


] 


return render_template('index.html', title='Home', user=user, posts=posts) 


我 使 用 了 一 个 列表 来 表示 用 户 动态 ? 其 中 每 个 l 元 素 是 一 个 具有 author 和 body 字段 的 字典 © 
未 来 设计 用 户 和 其 动态 时 ， 我 将 尽 可 有 EE 地 保留 这 些 字 段 名 称 ， 以 便 在 使 用 监 实用 户 和 其 动态 
的 时 候 不 会 出 现 问 题 。 


在 模板 方面 ， 我 必须 解决 一 个 新 问题 。 用 户 动 态 列表 拥有 的 元 素数 量 由 视图 函数 决定 。 MA 
模板 不 能 对 有 多 少 个 用 户 动 态 进 行 任何 假设 ， 因 此 需要 准备 好 以 通用 方式 泻 染 任意 数量 的 用 
户 动态 。 


Jinja2 提 供 了 for 控制 结构 来 应 对 这 类 问题 : 


<html> 
<head> 
{% if title %} 
<title>{{ title }} - Microblog</title> 
{% else %} 
<title>welcome to Microblog</title> 
{% endif %} 
</head> 
<body> 
<hi>Hi, {{ user.username }}!</h1i> 
{% for post in posts %} 
<div><p>{{ post.author.username }} says: <b>{{ post.body }}</b></p></div> 
{% endfor %} 
</body> 
</html> 


大 道 至 简 ， 对 吧 ? 玩 玩 这 个 新 版 本 的 应 用 程序 ， 一 定 要 逐步 添加 更 多 的 内 容 到 用 户 动态 列 
表 ， 看 看 模板 如 何 调度 以 展现 视图 沟 数 传 入 的 所 有 用 户 动态 。 


iW Home Page - Microblog 
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Hi, Miguel! 


John says: Beautiful day in Portland! 





Susan says: The Avengers movie was so cool! 


模板 的 继承 


绝 大 多 数 Web 应 用 程序 在 页 面 的 顶部 都 有 一 个 导航 栏 ， 其 中 带 有 一 些 常 用 的 链接 ， 例 如 编辑 
配置 文件 ， 登 录 ， 注 销 等 。 我 可 以 轻松 地 用 HTML 标 记 语言 将 导航 栏 添 如 到 index.html 模板 
上 ， 但 随 着 应 用 程序 的 增长 ， 我 将 需要 在 其 他 页 面 重复 同样 的 工作 。 尽 量 不 要 编写 重复 的 代 
码 ， 这 是 一 个 良好 的 编程 习惯 ， 毕 竟 我 真 的 不 想 在 诸多 HTML 模 板 上 保留 同样 的 代码 。 


Jinja2 有 一 个 模板 继承 特性 ， 专 门 解决 这 个 问题 。 从 本 质 上 来 讲 ， 就 是 将 所 有 模板 中 相同 的 部 
分 转移 到 一 个 基础 模板 中 ， 然 后 再 从 它 继承 过 来 。 


所 以 我 现在 要 做 的 是 定义 一 个 名 为 base.html 的 基本 模板 ， 其 中 包含 一 个 简单 的 导航 栏 ， 以 
及 我 之 前 实现 的 标题 逻辑 。 您 需要 在 模板 文件 app/templates/base.htm/ 中 编写 代码 如 下 : 


<html> 

<head> 
{% if title %} 
<title>{{ title }} - Microblog</title> 
{% else %} 
<title>welcome to Microblog</title> 
{% endif %} 

</head> 


<body> 
<div>Microblog: <a href="/index">Home</a></div> 


<hr> 
{% block content %}{% endblock %} 


</body> 
</html> 


在 这 个 模板 中 ， 我 使 用 block 控制 语 如 来 定义 派生 模板 可 以 插入 代码 的 位 置 。 block IAP — 
个 唯一 的 名 称 ， 派 生 的 模板 可 以 在 提供 其 内 容 时 进行 引用 。 


通过 从 基础 模板 base.html 继 承 HTML 元 素 ， 我 现在 可 以 简化 模板 index.html 了 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Hi, {{ user.username }}!</h1> 


{% for post in posts %} 
<div><p>{{ post.author.username }} says: <b>{{ post.body }}</b></p></div> 


{% endfor %} 
{% endblock %} 


自从 基础 模板 base.html 接 手 页 面 的 布局 之 后 ， 我 就 可 以 从 index.htm/ 中 删除 所 有 这 方面 的 元 

素 ， 只 留 下 内 容 部 分 。 extends 语句 用 来 建立 了 两 个 模板 之 间 的 继承 关系 ， 这 样 Jinja2 才 知道 
当 要 求 呈现 index.html 时 ， 需 要 将 其 能 入 到 base.html Po 而 两 个 模板 中 匹配 的 block 4 
和 其 名 称 content ， 让 Jinja2 知 道 如 何 将 这 两 个 模板 合并 成 在 一 起 。 现 在 ， 扩 展 应 用 程序 的 页 
面 就 变 得 极其 方便 了 ， 我 可 以 创建 从 同一 个 基础 模板 base.html 继 承 的 派生 模板 ， 这 就 是 我 让 


应 用 程序 的 所 有 页 面 拥有 统一 外 观 布局 而 不 用 重复 编写 代码 的 秘诀 。 


四 Home Page - Microblog 
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Microblog: Home 





Hi, Miguel! 
John says: Beautiful day in Portland! 


Susan says: The Avengers movie was so cool! 


本 文 翻 译 自 The Flask Mega-Tutorial Part Ill: Web Forms 
这 是 Flask Mega-Tutorial 系 列 的 第 三 部 分 ， 我 将 告诉 你 如 何 使 用 Web 表 单 。 


在 第 二 章 中 我 为 应 用 主页 创建 了 一 个 简单 的 模板 ， 并 使 用 诸如 用 户 和 用 户 动态 的 模拟 对 象 。 
在 本 章 中 ， 我 将 解决 这 个 应 用 程序 中 仍然 存在 的 众多 遗漏 之 一 ， 那 就 是 如 何 通过 VVeb 表 单 接 
受用 户 的 输入 。 


Web 表 单 是 所 有 Web 应 用 程序 中 最 基本 的 组 成 部 分 之 一 。 我 将 使 用 表单 来 为 用 户 发 表 动 态 和 
登录 认证 提供 途径 。 


在 继续 阅读 本 章 之 前 ， 确 保 你 的 microblog 应 用 程序 状态 和 上 一 章 完 结 时 一 致 ， 并 且 运 行 时 不 
会 报 任何 错误 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


Flask-WTF 简 介 


我 将 使 用 Flask-WTF 播 件 来 处 理 本 应 用 中 的 Web 表 单 ， 它 对 WTForms 进 行 了 浅 层 次 的 封装 以 
便 和 Flask 完 美 结 合 。 这 是 本 应 用 引入 的 第 一 个 Flask 插 件 ， 但 绝 不 是 最 后 一 个 。 插 件 是 Flask 
生态 中 的 举足轻重 的 一 部 分 ，Flask 故 意 设计 为 只 包含 核心 功能 以 保持 代码 的 整洁 ， 并 暴露 接 
口 以 对 接 解决 不 同 问题 的 插件 。 


Flask 插 件 都 是 常规 的 Python 三 方 包 ， 可 以 使 用 pip 安装 。 那 就 继续 在 你 的 虚拟 环境 中 安装 
Flask-WTF 吧 : 


(venv) $ pip install flask-wtf 


AC A. 


到 目前 为 止 ， 这 个 应 用 程序 都 非常 简单 ， 因 此 我 不 需要 考虑 它 的 配置 。 但 是 ， 除 了 最 简单 的 
应 用 ， 你 会 发 现 Flask (也 可 能 是 Flask 插 件 ) 为 使 用 者 提供 了 一 些 可 自由 配置 的 选项 。 你 需要 
决定 传 入 什么 样 的 配置 变量 列表 到 框架 中 。 


有 几 种 途径 来 为 应 用 指定 配置 选项 。 最 基本 的 解决 方案 是 使 用 app,config 对 象 ， 它 是 一 个 类 
似 字典 的 对 象 ， 可 以 将 配置 以 键 值 的 方式 存储 其 中 。 例 如 ， 你 可 以 这 样 做 : 


app = Flask(__name_) 
app.config['SECRET_KEY'] = 'you-will-never-guess' 
# =... add more variables here as needed 


LHR RATAA ROAR RRA HB o Alk> KAA EE A 
代码 处 于 同一 个 部 分 ， 而 是 使 用 稍微 复杂 点 的 结构 ， 将 配置 保存 到 一 个 单独 的 文件 中 。 
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以 保持 良好 的 组 织 结构 。 下 面 就 让 你 见识 一 下 这 个 存储 在 顶级 目录 下 ， 名 为 config.py 的 模块 
的 配置 类 吧 : 


import os 


class Config(object): 
SECRET_KEY = os.environ.get('SECRET_KEY') or 'you-will-never-guess' 


简单 的 不 像 话 ， 有 没有 ? 配置 设置 被 定义 为 config 类 中 的 属性 。 一 旦 应 用 程序 需要 更 多 配 
置 选项 ， 直 接 依 样 画 靖 芦 ， 附 加 到 这 个 类 上 即 可 ， 稍 后 如 果 我 发 现 需要 多 个 配置 集 ， 则 可 以 
创建 它 的 子 类 。 现 在 则 不 用 操心 。 


SECRET_KEY 是 我 添加 的 唯一 配置 选项 ， 对 大 多 数 Flask 应 用 来 说 ， 它 都 是 极其 重要 的 。Flask 
及 其 一 些 扩 展 使 用 密 钥 的 值 作 为 加 密 密 铀 ， 用 于 生成 签名 或 令 牌 。Flask-WTF 插 件 使 用 它 来 保 
护 网 页 表单 免 受 名 为 Cross-Site Request Forgery 或 CSRF (发 音 为 “seasurf') 的 恶意 攻击 。 
顾名思义 ， 密 钥 应 该 是 隐 密 的 ， 因 为 由 它 产生 的 令 牌 和 签名 的 加 密 强 度 保证 ， 取 决 于 除了 可 
信 维 护 者 之 外 ， 没 有 任何 人 能 够 获得 它 。 


密 钥 被 定义 成 由 or 运算 符 连接 两 个 项 的 表达 式 。 第 一 个 项 查找 环境 变量 SECRET_KEY 的 值 ， 
第 二 个 项 是 一 个 硬 编码 的 字符 囊 。 这 种 首先 检查 环境 变量 中 是 否 存 在 这 个 配置 ， 找 不 到 的 情 
况 下 就 使 用 硬 编码 字符 串 的 配置 变量 的 模式 你 将 会 反复 看 到 。 在 开发 阶段 ， 安 全 性 要 求 较 

低 ， 因 此 可 以 直接 使 用 硬 编码 字符 串 。 但 是 ， 当 应 用 部 署 到 生产 服务 器 上 的 时 候 ， 我 将 设置 
一 个 独一无二 且 难 以 揣摩 的 环境 变量 ， 这 样 ， 服 务 器 就 拥有 了 一 个 别人 未 知 的 安全 密 钥 了 。 


拥有 了 这 样 一 份 配置 文件 ， 我 还 需要 通知 Flask 读 取 并 使 用 它 。 可 以 在 生成 Flask 应 用 之 后 ， 利 
用 app.config.from_object() 方法 来 完成 这 个 操作 : 

from flask import Flask 

from config import Config 


app = Flask(__name_) 
app.config.from_object (Config) 


from app import routes 


导入 config 类 的 方式 ， 乍 一 看 可 能 会 让 人 感到 困惑 ， 不 过 如 果 你 注意 到 从 flask 包 导 
入 Flask 类 的 过 程 ， 就 会 发 现 这 其 实 是 类 似 的 操作 。 显而易见 ， 小 写 的 “config" 是 Python 模 
块 config.py 的 名 字 ， 另 一 个 含有 大 写 “C” 的 是 类 。 


正如 我 上 面 提 到 的 ， 可 以 使 用 app.config 中 的 字典 语法 来 访问 配置 项 。 在 下 面 的 Python 交互 
式 会 话 中 ， 你 可 以 看 到 密 钥 的 值 : 
>>> from microblog import app 


>>> app.config[ 'SECRET_KEY' ] 
"you-will-never-guess' 


用 户 登录 表单 


Flask-WTF 插 件 使 用 Python 类 来 表示 Web 表 单 。 表 单 类 只 需 将 表单 的 字段 定义 为 类 属性 即 
可 o 


为 了 再 次 践 行 我 的 松 耦 合 原则 ， 我 会 将 表单 类 单独 存储 到 名 为 app/forms.py 的 模块 中 。 就 让 我 
们 来 定义 用 户 登 录 表 单 来 做 一 个 开始 吧 ， 它 会 要 求 用 户 输入 username 和 password， 并 提供 一 
个 “remember me” 的 复 选 框 和 提交 按钮 : 


from flask_wtf import FlaskForm 
from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import DataRequired 


class LoginForm(FlaskForm) : 
username = StringField('Username', validators=[DataRequired()]) 
password = PasswordField('Password', validators=[DataRequired()]) 
remember_me = BooleanField('Remember Me' ) 
submit = SubmitField('Sign In') 


大 多 数 Flask 插 件 使 用 flask_ <name> 命名 约定 来 导入 ，Flask-WTF 的 所 有 内 容 都 
在 flask_wtf 包 中 。 在 本 例 中 ，app/forms.py 模 块 的 顶部 从 flask_wtf FATS 
为 FlaskForm 的 基 类 o 


由 于 Flask-WTF 播 件 本 身 不 提供 字段 类 型 ， 因 此 我 直接 从 WTForms 包 中 导入 了 四 个 表示 表单 
字段 的 类 。 每 个 字段 类 都 接受 一 个 描述 或 别名 作为 第 一 个 参数 ， 并 生成 一 个 实例 来 作 
为 LoginForm 的 类 属性 。 


你 在 一 些 字段 中 看 到 的 可 选 参 数 validators 用 于 验证 输入 字段 是 否 符合 预 
期 。 pataRequired 验证 器 仅 验证 字段 输入 是 否 为 空 。 更 多 的 验证 器 将 会 在 未 来 的 表单 中 接触 


到 ° 


表单 模板 


下 一 步 是 将 表单 添加 到 HTML 模 板 以 便 泻 染 到 网 页 上 。 令 人 高 兴 的 是 在 LoginForm 类 中 定义 的 
字段 支持 自 浑 染 为 HTML 元 素 ， 所 ee 当 简 单 。 我 将 把 登录 模板 存储 在 文件 
app/templates/login.html 中 ， 代 码 如 下 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Sign In</h1> 


<form action=""_ method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.username.label }}<br> 
{{ form.username(size=32) }} 
</p> 
<p> 
{{ form.password.label }}<br> 
{{ form.password(size=32) }} 
</p> 
<p>{{ form.remember_me() }} {{ form.remember_me.label }}</p> 
<p>{{ form.submit() }}</p> 
</form> 
{% endblock %} 


一 如 第 二 章 ， 在 这 个 模板 中 我 再 次 使 用 了 extends 来 继承 base.html 基础 模板 。 事 实 上 ， 我 
将 会 对 所 有 的 模板 继承 基础 模板 ， 以 保持 顶部 导航 栏 风格 统一 。 


这 个 模板 需要 一 个 form 参 数 的 传 入 到 泻 染 模板 的 函数 中 ，form 来 自 于 LoginForm 类 的 实例 
化 ， 不 过 我 现在 还 没有 编写 它 。 


HTML <form> 元 素 被 用 作 VWeb 表 单 的 容器 。 表单 的 action 属性 告诉 浏览 器 在 提交 用 户 在 表 
单 中 输入 的 信息 时 应 该 请 求 的 URL。 4 action 设置 为 空 字符 串 时 ， 表 单 将 被 提交 给 当前 地 址 
栏 中 的 URL， 即 当前 页 面 。 method 属性 指定 了 将 表单 提交 给 服务 器 时 应 该 使 用 的 HTTP 请 求 
方法 。 默 认 情 况 下 是 用 cet 请 求 发 送 ， 但 几乎 在 所 有 情况 下 ， 使 用 post 请 求 会 提供 更 好 的 
用 户 体 验 ， 因 为 这 种 类 型 的 请 求 可 以 在 请 求 的 主体 中 提交 表单 数据 ， GET 请 求 将 表单 字段 添 
加 到 URL， 会 使 浏览 器 地 址 栏 变 得 混乱 。 


form.hidden_tag() 模板 参数 生成 了 一 个 隐藏 字段 ， 其 中 包含 一 个 用 于 保护 表单 免 受 CSRF 攻 
HA) token 。 对 于 保护 表单 ， 你 需要 做 的 所 有 事情 就 是 在 模板 中 包括 这 个 隐藏 的 字段 ， 并 在 
Flask 配 置 中 定义 SECRET_KEY 变量 ，Flask-WTF 会 完成 剩 下 的 工作 。 


如 果 你 以 前 编写 过 HTML Web 表 单 ， 那 么 你 会 发 现 一 个 奇怪 的 现象 一 一 在 此 模板 中 没有 HTML 
表单 元 素 ， 这 是 因为 表单 的 字段 对 象 的 在 泻 染 时 会 自动 转化 为 HTML 元 素 。 我 只 需 在 需要 字 

段 标 签 的 地 方 加 上 {{ form.<field_name>.label }} ， 需要 这 个 字段 的 地 方 加 

上 {{ form.<field_name>() }} ° 对 于 需要 附加 HTML 属 性 的 字段 ， 可 以 作为 关键 字 参 数 传递 

到 函数 中 。 此 模板 中 的 username 和 password 字 段 将 size 作为 参数 ， 将 其 作为 属性 添加 

到 <input> HTML 元 素 中 。 你 页 也 可 以 通过 这 种 手段 为 表单 字段 设置 class 和 id 属性 。 


表单 视图 
完成 这 个 表单 的 最 后 一 步 就 是 编写 一 个 新 的 视图 函数 米 泻 染 上 面 创建 的 模板 。 


函数 的 逻辑 只 需 创 建 一 个 form 实 例 ， 并 将 其 传 入 泻 染 模板 的 函数 中 即 可 ， 然 后 用 /Mogin URL 来 
关联 它 。 这 个 视图 函数 也 存储 到 app/routes.py 模 块 中 ， 代 码 如 下 : 


from flask import render_template 
from app import app 
from app.forms import LoginForm 


# i... 


@app.route('/login' ) 
def login(): 
form = LoginForm() 
return render_template('login.html', title='Sign In', form=form) 


我 从 forms.py 导 入 LoginForm 类 ， 并 生成 了 一 个 实例 传 入 模板 。 form=form 的 语法 看 起 来 奇 
怪 ， 这 是 Python 函数 或 方法 传 入 关键 字 参 数 的 方式 ， 左 边 的 form 代表 在 模板 中 引用 的 变量 名 
称 ， 右 边 则 是 传 入 的 Jorm 实 例 。 这 就 是 获取 表单 字段 泻 染 结果 的 所 有 代码 了 。 


在 基础 模板 templates/base.html 的 导航 栏 上 添加 登录 的 链接 ， 以 便 访问 : 


<div> 
Microblog: 
<a href="/index">Home</a> 
<a href="/login">Login</a> 
</div> 


= 


此 时 ， 你 可 以 验证 结果 了 。 运 行 该 应 用 ， 在 浏览 器 的 地 址 栏 中 输入 http://localhost:5000/ ， 
然后 点 击 顶 部 导航 栏 中 的 “Login" 链 接 来 查看 新 的 登录 表单 。 是 不 是 非常 炫 酷 ? 
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Username 
Password 


Remember Me 


Sign in | 


接收 表单 数据 


F ， 浏览 器 将 显示 “Method Not Allowed” 错 误 。 为 什么 呢 ? 这 是 因为 之 前 的 登录 视 

图 功能 到 目前 为 止 只 完成 了 一 To 。 它 可 以 在 网 页 上 显示 表单 ， 但 没有 逻辑 来 处 理 用 户 
提 3 o ° Flask-WTF T AERARII LE” AFERA RAEE > CRE 
验证 用 户 提交 的 数据 : 


from flask import render_template, flash, redirect 


@app.route('/login', methods=['GET', 'POST']) 
def login(): 
form = LoginForm() 
if form.validate_on_submit(): 
flash('Login requested for user {}, remember_me={}'. format ( 
form.username.data, form.remember_me.data) ) 
return redirect('/index' ) 
return render_template('login.html', title='Sign In', form=form) 


这 个 版 本 中 的 第 一 个 新 东西 是 路 由 装饰 器 中 的 methods 参数 。 它 告 诉 Flask 这 个 视图 函数 接 
Z GET 和 post HR? HBS T Ri cet 。 HTTP 协 议 规定 对 GET 请 ona. 言 息 给 客 
户 端 (本 例 中 是 浏览 器 ) 。 本 应 用 的 所 有 GET 请 求 都 是 如 此 。 当 浏 览 器 向 服务 器 提交 表单 数 
据 时 ， 通 常会 使 用 post 请 求 (实际 上 用 cer 请 求 也 可 以 ， 但 这 on ag 。 之 前 

的 “Method Not Allowed" 错 误 正 是 由 于 视图 函数 还 未 配置 允许 post 请 求 。 通 过 传 

入 methods 参数 ， 你 就 能 告诉 Flask 哪 些 请 求 方法 可 以 被 接受 。 


form.validate_on SSM) 实例 方法 会 执行 form 校 验 的 工作 。 当 浏览 器 发 起 GET 请 求 的 时 
候 ， 它 返回 False ， 这 样 视 图 函数 就 会 跳 过 if 块 中 的 代码 ， 直 接 转 到 视图 函数 的 最 后 一 名 
来 泻 染 模板 。 


当 用 户 在 浏览 器 aaa 交 按 钮 后 ， 浏 览 器 会 发 送 post 请 求 。 form.validate_on_submit() 就 会 
获取 到 所 有 的 数据 ， 运 行 字段 各 自 的 验证 器 ， ee 寺 之 后 就 会 返回 True ， 这 表示 数据 有 
效 。 不 过 ， a ， 这 个 实例 方法 就 会 返回 False ， 引 发 类 

似 GET 请 求 那样 的 表单 的 泻 染 并 返回 给 用 户 。 稍 后 我 会 在 添加 代码 以 实现 在 验证 失败 的 时 候 
显示 一 条 错误 消息 。 


当 form.validate_on_submit() 返回 True 时 ， 登 录 视 图 函数 调用 从 Flask 导 入 的 两 个 新 函数 。 
flash() 函数 是 向 用 户 显 示 消 息 的 有 效 途径 。 许 多 应 用 使 用 这 个 技术 来 让 用 户 知道 某 个 动作 
是 否 成 功 。 我 将 使 用 这 种 机 制作 为 临时 解决 方案 ， 因 为 我 没有 基础 架构 来 趴 正 地 登录 用 户 。 

显示 一 条 消息 来 确认 应 用 已 经 收 到 登录 认证 凭据， 我 认为 对 当前 来 说 已 经 足够 了 。 


登录 视图 函数 中 使 用 的 第 二 个 新 函数 是 redirect() 。 这 个 函数 指引 浏览 器 自动 重 定向 到 它 的 
参数 所 关联 的 URL。 当 前 视图 函数 使 用 它 将 用 户 重 定向 到 应 用 的 主页 。 


当 你 调用 flash() 元 数 后 ，Flask 会 存储 这 个 消息 ， 但 是 却 不 会 奇迹 般 地 直接 出 现在 页 面 上 。 
模板 需要 将 消息 泻 染 到 基础 模板 中 ， 才 能 让 所 有 派生 出 来 的 模板 都 能 显示 出 来 。 更 新 后 的 基 
础 模板 代码 如 下 : 


<html> 
<head> 
{% if title %} 
<title>{{ title }} - microblog</title> 
{% else %} 
<title>microblog</title> 
{% endif %} 
</head> 
<body> 
<div> 
Microblog: 
<a href="/index">Home</a> 
<a href="/login">Login</a> 
</div> 
<hr> 
{% with messages = get_flashed_messages() %} 
{% if messages %} 
<ul> 
{% for message in messages %} 
<li>{{ message }}</1li> 
{% endfor %} 
</ul> 
{% endif %} 
{% endwith %} 
{% block content %}{% endblock %} 
</body> 
</html> 


此 处 我 用 了 with 结构 在 当前 模板 的 上 下 文中 来 将 get_flashed_messages() 的 结果 赋值 给 变 
量 messages ° get_flashed_messages() 是 Flask 中 的 一 个 函数 ， 它 返回 用 flash() 注册 过 的 消 
息 列表 。 接 下 来 的 条 件 结 构 用 来 检查 变量 messages 是 否 包 含 元 素 ， 如 果 有 ， 则 在 <ul> TH 
中 ， 为 每 条 消息 用 <i> 元 素来 包 庄 泻 染 。 这 种 泻 染 的 样式 结果 看 起 来 不 会 美观 ， 之 后 会 有 主 
题 讲 到 Web 应 用 的 样式 。 


闪现 消息 的 一 个 有 趣 的 属性 是 ， 一 旦 通过 get_flashed_messages 函数 请 求 了 一 次 ， 它 们 就 会 从 
消息 列表 中 移 除 ， 所 以 在 调用 flash() 函数 后 它们 只 会 出 现 一 次 。 


时 机 成 熟 ， 再 次 测试 表单 吧 ， 将 username 和 password 字 段 留 空 并 点 击 提交 按钮 来 观 
察 DataRequired 验证 器 是 如 何 中 断 提交 处 理 流程 的 。 


完善 字段 验证 
表单 字段 的 验证 器 可 防止 无 效 数据 被 接收 到 应 用 中 。 应 用 处 理 无 效 表单 输入 的 方式 是 重新 显 
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如 果 你 尝试 过 提交 无 效 的 数据 ， 相 信 你 会 注意 到 ， 虽 然 验证 机 制 查 无 遗漏 ， 却 没有 给 出 表单 
草 误 的 具体 线索 。 下 一 个 任务 是 通过 在 验证 失败 的 每 个 字段 旁边 添加 有 意义 的 错误 消息 来 改 
EP URS o 


实际 上 ， 表 单 验 证 器 已 经 生成 了 这 些 描述 性 错误 消息 ， 所 缺少 的 不 过 是 模板 中 的 一 些 额外 的 
逻辑 来 泻 染 它们 。 


这 是 给 username 和 password 字 段 添 加 了 验证 描述 性 错误 消息 演 染 逻辑 之 后 的 登录 模板 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Sign In</h1i> 


<form action="" method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.username.label }}<br> 
{{ form.username(size=32) }}<br> 
{% for error in form.username.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.password.label }}<br> 
{{ form. password(size=32) }}<br> 
{% for error in form.password.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p>{{ form.remember_me() }} {{ form.remember_me.label }}</p> 

<p>{{ form.submit() }}</p> 

</form> 
{% endblock %} 


人 添加 for 循 环 以 便 用 红色 字体 来 泻 染 验 

证 器 添加 的 错误 信息 。 通 常情 况 下 ， 拥 有 验证 器 的 字段 都 会 用 form.<field_name>.errors 来 泻 

染 错 误 信 息 。 一 个 字段 的 验证 错误 信息 结果 是 一 个 列表 ， 因 为 字段 可 以 附加 多 个 验证 器 ， 并 
多 个 验证 器 都 可 能 会 提供 错误 消息 以 显示 给 用 户 。 


如 果 你 尝试 在 未 填写 username 和 password 字 段 的 情况 下 提交 表单 ， 就 可 以 看 到 显眼 的 红色 错 
误 信 息 了 。 
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生成 链接 


现在 的 登录 表单 已 经 相当 完整 了 ， 但 在 结束 本 章 之 前 ， 我 想 讨 论 在 模板 和 重 定向 中 包含 链接 
的 妥当 方法 。 到 目前 为 止 ， 你 已 经 看 到 了 一 些 定义 链接 的 例子 。 例 如 ， 这 是 当前 基础 模板 中 
的 导航 栏 代码 : 


<div> 
Microblog: 
<a href="/index">Home</a> 
<a href="/login">Login</a> 
</div> 


登录 视图 函数 同样 定义 了 一 个 传 入 到 redirect() 函数 作为 参数 的 链接 : 


@app.route('/login', methods=['GET', 'POST']) 
def login(): 
form = LoginForm() 
if form.validate_on_submit(): 
# a. 
return redirect('/index' ) 


直接 在 模板 和 源 文 件 中 硬 编 码 链接 存在 隐患 ， 如 果 有 一 天 你 决定 重新 组 织 链接 ， 那 么 你 将 不 
得 不 在 整个 应 用 中 搜索 并 替换 这 些 链接 。 


为 了 更 好 地 管理 这 些 链接 ，Flask 提 供 了 一 个 名 为 url_for() 的 函数 ， 它 使 用 URL 到 视图 函数 
的 内 部 映射 关系 来 生成 URL。 例如，url for('login') 返回 /login ，url for('index') 返 
回 /index ° url_for() 的 参数 是 enqdpoint 名 称 ， 也 就 是 视图 函数 的 名 字 。 


你 可 能 会 问 ， 为 什么 使 用 函数 名 称 而 不 是 URL ? 事实 是 ，URL 比 起 视图 函数 名 称 变更 的 可 能 
性 更 高 。 稍 后 你 会 了 解 到 的 第 二 个 原因 是 ， 一 些 URL 中 包含 动态 组 件 ， 手 动 生 成 这 些 URL 需 
要 连接 多 个 元 素 ， 枯 燥 乏 味 且 容易 出 错 。 url for() 生成 这 种 复杂 的 URL 就 方便 许多 。 


因此 ， 从 现在 起 ， 一 旦 我 需要 生成 应 用 链接 ， 我 就 会 使 用 url_for() 。 基 础 模板 中 的 导航 栏 
部 分 代码 变更 如 下 : 


<div> 
Microblog: 
<a href="{{ url_for('index') }}">Home</a> 
<a href="{{ url_for('login') }}">Login</a> 
</div> 


login() 视图 函数 也 做 了 相应 变更 : 


from flask import render_template, flash, redirect, url_for 
HRS 


@app.route('/login', methods=['GET', 'POST']) 
def login(): 
form = LoginForm() 
if form.validate_on_submit(): 
# ... 
return redirect(url_for('index')) 


本 文 翻 译 自 The Flask Mega-Tutorial Part IV: Database 
在 Flask Mega-Tutorial 系 列 的 第 四 部 分 ， 我 将 告诉 你 如 何 使 用 数据 库 。 


本 章 的 主题 是 重 中 之 重 ! 大 多 数 应 用 都 需要 持久 化 存储 数据 ， 并 高 效 地 执行 的 增删 查 改 的 操 
作 ， 数 据 库 为 此 而 生 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


Flask 中 的 数据 库 


Flask 本 身 不 支持 数据 库 ， 相 信 你 已 经 听 说 过 了 。 正如 表单 那样 ， 这 也 是 Flask 有 意 为 之 。 对 
使 用 的 数据 库 插件 自由 选择 ， 岂 不 是 比 被 迫 适 应 其 中 之 一 ， 更 让 人 拥有 主动 权 吗 ? 


绝 大 多 数 的 数据 库 都 提供 了 Python 客户 端 包 ， 它 们 之 中 的 大 部 分 都 被 封装 成 Flask 插 件 以 便 更 
好 地 和 Flask 应 用 结合 。 数 据 库 被 划分 为 两 大 类 ， 遵 循 关系 模型 的 一 类 是 关系 数据 库 ， 另 外 的 
则 是 非 关 系数 据 库 ， 简 称 NoOSQL， 表 现在 它们 不 支持 流行 的 关系 查询 语言 SQL ( 译 者 注 : 部 
分 人 也 宣称 NOSQL 代 表 不 仅仅 只 是 SQL ) 。 虽 然 两 类 数据 库 都 是 伟大 的 产品 ， 但 我 认为 关系 
数据 库 更 适合 具有 结构 化 数据 的 应 用 程序 ， 例 如 用 户 列 表 ， 用 户 动态 等 ， 而 NoSQL 数 据 库 往 
往 更 适合 非 结构 化 数据 。 本 应 用 可 以 像 大 多 数 其 他 应 用 一 样 ， 使 用 任何 一 种 类 型 的 数据 库 来 
实现 ， 但 是 出 于 上 述 原 因 ， 我 将 使 用 关系 数据 库 。 


在 第 三 章 中 ， a 一 个 Flask 扩 展 ， 在 本 章 中 ， 我 还 要 用 到 两 个 。 第 一 个 是 Flask- 
SQLAIchemy， 这 个 插件 为 流行 的 SQLAIchemy 包 做 了 一 层 封装 以 便 在 Flask 中 调用 更 方便 > 
类 似 SQLAIchemy 这 样 的 包 叫 做 Object Relational Mapper > ORM ° ORM 人 允许 应 用 程序 
使 用 高 级 实体 〈 如 类 ， 对 象 和 方法 ) 而 不 是 表 和 SQL 来 管理 数据 库 。ORM 的 工作 就 是 将 高 级 
操作 转换 成 数据 库 命令 。 


SQLAIchemy 不 只 是 茶 一 款 数 据 库 软 件 的 ORM ， 而 是 支持 包含 MySQL、PostgreSQL 和 
SQLite 在 内 的 很 多 数据 库 软 件 。 简 直 是 太 强 大 了 ， 你 可 以 在 开发 的 时 候 使 用 简单 易 用 且 无 需 
另 起 服 务 的 SQLite， 需 要 部 署 应 用 到 生产 服务 器 上 时 ， 则 选用 更 健壮 的 MySQL 或 PostgreSQL 
服务 ， 并 且 不 需要 修改 应 用 代码 ( 译 者 注 : 只 需 修改 应 用 配置 ) © 


确认 激活 虚拟 环境 之 后 ， 利 用 如 下 命令 来 安装 Flask-SQLAIchemy 插 件 : 


(venv) $ pip install flask-sqlalchemy 


数据 库 迁 移 


我 所 见 过 的 绝 大 多 数 数据 库 教 程 都 是 关于 如 何 创 建 和 使 用 数据 库 的 ， 却 没有 指出 当 需 要 对 现 

有 数据 库 更 新 或 者 添加 表 结 构 时 ， 应 当 如 何 应 对 。 这 是 一 项 困难 的 工作 ， 因 为 关系 数据 库 是 

以 结构 化 数据 为 中 心 的 ， 所 以 当 结 构 发 生变 化 时 ， 数 据 库 中 的 已 有 数据 需要 被 迁移 到 修改 后 
结构 中 。 


我 将 在 本 章 中 介绍 的 第 二 个 插件 是 Flask-Migrate。 这 个 插件 是 Alembic 的 一 个 Flask 封 装 ， 是 
SQLAIchemy 的 一 个 数据 库 迁 移 框 架 。 使 用 数据 库 迁 移 增加 了 启动 数据 库 时 候 的 一 些 工作 ， 
但 这 对 将 来 的 数据 库 结构 稳健 变更 来 说 ， 是 一 个 很 小 的 代价 。 


安装 Flask-Migrate 和 安装 你 见 过 的 其 他 插件 的 方式 一 样 : 


(venv) $ pip install flask-migrate 


Flask-SQLAlIchemy é¢ 4 


开发 阶段 ， 我 会 使 用 SQLite 数 据 库 ，SQLite 数 据 库 是 开发 小 型 万 至 中 型 应 用 最 方便 的 选择 ， 
因为 每 个 数据 库 都 存储 在 磁盘 上 的 单个 文件 中 ， 并 且 不 需要 像 MySQL 和 PostgreSQL 那 样 运行 
数据 库 服 务 。 


让 我 们 给 配置 文件 添加 两 个 新 的 配置 项 : 


import os 
basedir = os.path.abspath(os.path.dirname(__file_)) 


class Config(object): 
# ... 
SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or \ 
"sqlite:///' + os.path.join(basedir, 'app.db') 
SQLALCHEMY_TRACK_MODIFICATIONS = False 


Flask-SQLAIchemy 插 件 从 SQLALCHEMY_DATABASE_URI 配置 变量 中 获取 应 用 的 数据 库 的 位 置 。 

当 回 顾 第 三 草 可 以 发 现 ， 首 先 从 环境 变量 获取 配置 变量 ， 未 获取 到 就 使 用 默认 值 ， 这 样 做 是 
一 个 好 习惯 。 本 处 ， 我 从 DATABASE_URL 环境 变量 中 获取 数据 库 URL， 如 果 没 有 定义 ， 我 将 其 
配置 为 basedir 变量 表示 的 应 用 顶级 目录 下 的 一 个 名 为 app.qb 的 文件 路 径 。 


SQLALCHEMY_TRACK_MODIFICATIONS 配置 项 用 于 设置 数据 发 生变 更 之 后 是 否 发 送信 号 给 应 用 ， 我 
不 需要 这 项 功能 ， 因 此 将 其 设置 为 False 。 


数据 库 在 应 用 的 表现 形式 是 一 个 数据 库 实 例 ， 数 据 库 迁移 引 敬 同样 如 此 。 它 们 将 会 在 应 用 实 
例 化 之 后 进行 实例 化 和 注册 操作 。 app/_init .py 文件 变更 如 下 : 


from flask import Flask 

from config import Config 

from flask_sqlalchemy import SQLAlchemy 
from flask_migrate import Migrate 


app = Flask(__name_) 
app.config.from_object (Config) 
db = SQLAlchemy (app) 

migrate = Migrate(app, db) 


from app import routes, models 


在 这 个 初始 化 脚本 中 我 更 改 了 三 处 。 首 先 ， 我 添加 了 一 个 db 对 象 来 表示 数据 库 。 然 后 ， 我 又 
添加 了 数据 库 迁 移 引 擎 migrate 。 这 种 注册 Flask 插 件 的 模式 希望 你 了 然 于 胸 ， 因 为 大 多 数 
Flask 插 件 都 是 这 样 初始 化 的 。 最 后 ， 我 在 底部 导入 了 一 个 名 为 models 的 模块 ， 这 个 模块 将 
会 用 来 定义 数据 库 结构 。 


数据 库 模 型 


定义 数据 库 中 一 张 表 及 其 字段 的 类 ， 通 常 叫 做 数据 模型 。ORM(SQLAIchemy) 会 将 类 的 实例 关 
联 到 数据 库 表 中 的 数据 行 ， 并 翻译 相关 操作 。 


就 让 我 们 从 用 户 模型 开始 吧 ， 利 用 WWW SQL Designer 工 具 ， 我 画 了 一 张 图 来 设计 用 户 表 的 
各 个 字段 ( 译 者 注 : 实际 表 名 为 User) 


INTEGER 





email VARCHAR (120) | 


password_hash VARCHAR (128) | 





id 字段 通常 存在 于 所 有 模型 并 用 作 主 键 。 每 个 用 户 都 会 被 数据 库 分 配 一 个 id 值 ， 并 存储 到 这 
个 字段 中 。 大 多 数 情 况 下 ， 主 键 都 是 数据 库 自动 赋值 的 ， 我 只 需要 提供 id 字段 作为 主键 即 
可 o 


username ， email 和 password_hash 字段 被 定义 为 FRE (数据库 术语 中 的 VARCHAR ) ， 并 
指定 其 最 大 长 度 ， 以 便 数据 库 可 以 优化 空间 使 用 率 。 username 和 email 字段 的 用 途 不 言 而 
"ay ? password_hash 字段 值得 提 一 下 。 我 想 确保 我 正在 构建 的 应 用 采用 安全 最 佳 实践 ， 因 此 
我 不 会 将 用 户 密 码 明文 存储 在 数据 库 中 。 明文 存储 密码 的 问题 是 ， 如 果 数 据 库 被 攻破 ， 攻 击 
者 就 会 获得 密码 ， 这 对 用 户 隐私 来 说 可 能 是 毁灭 性 的 。 如果 使 用 哈 希 密码 ， 这 就 大 大 提高 了 
安全 性 。 这 将 是 另 一 章 的 主题 ， 所 以 现在 不 需 分 心 。 


用 户 表 构思 完毕 之 后 ， 我 将 其 用 代码 实现 ， 并 存储 到 新 建 的 模块 appmmoaeljs.py 中 ， 代 码 如 


from app import db 


class User(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
username = db.Column(db.String(64), index=True, unique=True) 
email = db.Column(db.String(120), index=True, unique=True) 
password_hash = db.Column(db.String(128) ) 


def __repr__(self): 
return '<User {}>'.format(self.username ) 


上 面 创 建 的 User 类 继承 自 db.Model， 它 是 Flask-SQLAIchemy 中 所 有 模型 的 基 类 。 这 个 类 将 
表 的 字段 定义 为 类 属性 ， 字 段 被 创建 为 dp.column 类 的 实例 ， 类 型 以 及 其 他 可 选 

参数 ， 例 如 ， 可 选 参 数 中 允许 指示 哪些 字段 是 唯一 的 并 且 是 可 索引 的 ， 这 对 高 效 的 数据 检索 
十 分 重要 。 


BRA _repr MA 
到 repr_() 方法 的 运行 情况 


>>> from app.models import User 

>>> u = User(username='susan', email='susan@example.com' ) 
>>> u 

<User susan> 


创建 数据 库 迁 移 存 储 库 


上 一 节 中 创建 的 模型 类 定义 了 此 应 用 程序 的 初始 数据 库 结 构 (元 数据 ) 。 但 随 着 应 用 的 不 断 
增长 ， 很 可 能 会 新 增 、 修 改 或 删除 数据 库 结 构 。 Alembic (Flask-Migrate 使 用 的 迁移 框架 ) 将 
以 一 种 不 需要 重新 创建 数据 库 的 方式 进行 数据 库 结 构 的 变更 。 


这 是 一 个 看 起 来 相当 艰巨 的 任务 ， 为 了 实现 它 ，Alembic 维 护 一 个 数据 库 迁 移 存 储 库 ， 它 是 一 
个 存储 迁 o 目录 。 | 于 更 改 后 ， 都 需要 向 存储 库 中 添加 一 个 包含 更 


改 的 详细 信息 的 迁移 脚本 。 当 应 用 这 些 迁 移 脚 本 到 数据 库 时 ， 它 们 将 按照 创建 的 顺序 执行 。 

Flask-Migrate 通 过 flask 命令 暴露 来 它 的 子 命令 。 你 已 经 看 过 flask run ， 这 是 一 个 Flask 本 

Aaa o eden flask db 令 来 管理 与 数据 库 迁 移 相 关 的 所 有 事情 。 
么 让 我 们 通过 运行 Flask db init 来 创建 microblog 的 迁移 存储 库 : 


(venv) $ flask db init 
Creating directory /home/miguel/microblog/migrations ... done 
Creating directory /home/miguel/microblog/migrations/versions ... done 
Generating /home/miguel/microblog/migrations/alembic.ini ... done 
Generating /home/miguel/microblog/migrations/env.py ... done 
Generating /home/miguel/microblog/migrations/README ... done 
Generating /home/miguel/microblog/migrations/script.py.mako ... done 
Please edit configuration/connection/logging settings in 
"/home/miguel/microblog/migrations/alembic.ini' before proceeding. 


请 记 住 ， flask 命令 依赖 于 FLASK_APP 环境 变量 来 知道 Flask 应 用 入 口 在 哪里 。 对 于 本 应 用 ， 
正如 第 一 章 ， 你 需要 设置 FLASK_APP = microblog.py ° 


运行 迁移 初始 化 命令 之 后 ， 你 gn 目录 。 该 目录 中 包含 一 个 名 
为 versions 的 子 目 录 以 及 若干 文件 。 从 现在 起 ， 这 些 文件 就 是 你 项 目的 一 部 分 了 ， 应 该 添加 到 
代码 版 本 管理 中 去 。 


第 一 次 数据 库 迁 移 


包含 映射 到 user 数据 库 模型 的 用 户 表 的 迁移 存储 库 生 成 后 ， 是 时 候 创 建 第 一 次 数据 库 迁 和 

To 有 两 种 方法 来 创建 数据 库 迁 移 : 手动 或 自动 。 要 自动 生成 迁移 ， We 
型 定义 的 数据 库 模式 与 数据 库 中 当前 使 用 的 实际 数据 库 模 式 进行 比较 。 然后 ， 使 用 必要 的 更 
改 来 填充 迁移 脚本 ， 以 使 数据 库 模 式 与 应 用 程序 模型 匹配 。 当前 情况 是 ， 由 于 之 前 没有 数据 
库 ， 自 动迁 移 将 把 整个 User 模 型 添加 到 六 迁移 脚本 中 。 flask db migrate 子 命 令 生成 这 些 自动 
迁移 : 


(venv) $ flask db migrate -m "users table" 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.autogenerate.compare] Detected added table 'user' 

INFO [alembic.autogenerate.compare] Detected added index 'ix_user_email' on '['email' 


INFO [alembic.autogenerate.compare] Detected added index 'ix_user_username' on '['use 
rname']' 

Generating /home/miguel/microblog/migrations/versions/e517276bbic2_users_table.py .. 
. done 


通过 命令 输出 ， 你 可 以 了 解 到 Alembic 在 创建 迁移 的 过 程 中 执行 了 哪些 逻辑 
息 ， 通 常 可 以 忽略 。 之 后 的 输出 表明 检测 到 了 一 个 用 户 表 和 两 个 索引 。 然 
脚本 的 输出 路 径 。 e517276bb1c2 是 自动 生成 的 一 个 用 于 迁移 的 唯一 标识 (你 运行 的 结果 会 有 
所 不 同 ) 。 -m 可 选 参 数 为 迁移 添加 了 一 个 简短 的 注释 。 


G = 
yy 2 
oe 
x 
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生成 的 迁移 脚本 现在 是 你 项 目的 一 部 分 了 ， 需 要 将 其 合并 到 源 代码 管理 中 。 如 果 你 好 奇 ， 并 
检查 了 它 的 代码 ， 就 会 发 现 它 有 两 个 函数 叫 E 和 downgrade() ° upgrade() 函数 应 
用 迁移 ， downgrade() RAER AH > Alembic 通 过 使 用 降级 方法 可 以 将 数据 库 迁 移 到 历史 中 
的 任何 点 ， 甚 至 迁移 到 较 昌 的 版 本 。 


flask db migrate 命令 不 会 对 数据 库 进 行 任 何 更 改 ， 只 会 生成 迁移 脚本 。 要 将 更 改 应 用 到 数 
据 库 ， 必 须 使 用 flask db upgrade TA ° 


(venv) $ flask db upgrade 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.runtime.migration] Running upgrade -> e517276bbic2, users table 


因为 本 应 用 使 用 SQLite， 所 以 upgrade 命令 检测 到 数据 库 不 存在 时 ， 会 创建 它 (在 这 个 命令 
完成 之 后 ， 你 会 注意 到 一 个 名 为 app.db 的 文件 ， 即 SQLite 数 据 库 ) 。 在 使 用 类 似 MySQL 和 
PostgreSQL 的 数据 库 服 务 时 ， 必 须 在 运行 upgrade 之 前 在 数据 库 服务 器 上 创建 数据 库 。 


数据 库 升 级 和 降级 流程 


目前 ， 本 应 用 还 处 于 初期 阶段 ， 但 讨论 一 下 未 来 的 数据 库 迁 移 战略 也 无 伤 大 雅 。 假设 你 的 开 
发 计算 机 上 存 有 应 用 的 源 代码 ， 并 且 还 将 其 部 署 到 生产 服务 器 上 ， 运 行 应 用 并 上 线 提供 服 


务 。 


将 需要 做 许多 工作 。 无 论 是 在 你 的 开发 机 器 上 ， ee 器 上 ， pi Fa ce 
更 你 的 数据 库 结构 才能 完成 这 项 任务 


过 数据 库 迁 移 机 制 的 支持 ， We 将 生成 一 个 新 的 迁移 脚本 
flask db migrate ) ， 你 可 能 会 审查 它 以 确保 自动 生成 的 正确 性 ， 然 后 将 更 改 应 用 到 你 的 
开发 数据 库 ( flask db upgrade ) 。 Ioa 将 迁移 脚本 添加 到 源 代码 管理 并 提交 。 


当 准 备 将 新 版 本 的 应 用 发 布 到 生产 服务 器 时 ， 你 只 需要 获取 包含 新 增 迁 移 脚 本 的 更 新 版 本 的 
应 用 ， 然 后 运行 flask db upgrade 即 可 。 Alembic 将 检测 到 生产 数据 库 未 更 新 到 最 新 版 本 ， 并 
运行 在 上 一 版 本 之 后 创建 的 所 有 新 增 迁 移 脚本 。 


正如 我 前 面 提 到 的 ， flask db downgrade 命令 可 以 回 滚 上 次 的 迁移 。 虽然 在 生产 系统 上 不 太 
可 能 需要 此 选项 ， 但 在 开发 过 程 中 可 能 会 发 现 它 非常 有 用 。 你 可 能 已 经 生成 了 一 个 迁移 脚本 
ae 应 用 ， 只 是 发 现 所 做 的 更 改 并 不 完全 是 你 所 需要 的 。 在 这 种 情况 下 ， 可 以 降级 数据 
> 删除 迁移 脚本 ， 然 后 生成 一 个 新 的 来 蔡 换 它 。 


关系 数据 库 擅长 存储 数据 项 之 间 的 关系 。 考虑 用 户 发 表 动态 的 情况 ， 用户 将 在 user RPA 
一 个 记录 ， 并 且 这 条 用 户 动 态 将 在 post 表 中 有 一 个 记录 。 标记 谁 写 了 一 个 给 定 的 动态 的 最 
有 效 的 方法 是 链接 两 个 相关 的 记录 。 

一 旦 建立 了 用 户 和 动态 之 间 的 关系 ， 数 据 库 就 可 以 在 查询 中 展示 它 。 最 小 的 例子 就 是 当 你 看 
IE ete io 
可 能 想 知 道 这 个 用 户 写 的 所 有 动态 。 Flask-SQLAIlchemy 有 助 于 实现 这 两 种 查询 。 


让 我 们 扩展 数据 库 来 存储 用 户 动态 ， 以 查看 实际 中 的 关系 。 这 是 一 个 新 表 post 的 设计 ( 译 
者 注 : 实际 表 名 分 别 为 user 和 post) : 





password_ hash VARCHAR (128) | 


post 表 将 具有 必须 的 id 、 用 户 动态 的 body 和 timestamp 字段 。 除 了 这 些 预 期 的 字段 之 
外 ， 我 还 添加 了 一 个 userid 字段 ， 将 该 用 户 动态 链接 到 其 作者 。 你 已 经 看 到 所 有 用 户 都 有 
一 个 唯一 的 id 主键 ， 将 用 户 动态 链接 到 其 作者 的 方法 是 添加 对 用 户 id 的 引用 ， 这 正 

Æ userid 字段 所 在 的 位 置 。 这 个 userid 字段 被 称 为 外 键 。 上 面 的 数据 库 图 显示 了 外 键 作 
为 该 字段 和 它 引 用 的 表 的 id 字段 之 间 的 链接 。 这 种 关系 被 称 为 一 对 多 ， 因 为 "一 个 "用 户 写 
了 "多 "条 动态 。 


修改 后 的 app/models.py 如 下 : 


from datetime import datetime 
from app import db 


class User(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
username = db.Column(db.String(64), index=True, unique=True) 
email = db.Column(db.String(120), index=True, unique=True) 
password_hash = db.Column(db.String(128) ) 
posts = db.relationship('Post', backref='author', lazy='dynamic' ) 


def _ repr_ (self): 
return '<User {}>'.format(self.username) 


class Post(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
body = db.Column(db.String(140)) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 
user_id = db.Column(db.Integer, db.ForeignKey('user.id')) 


def _ repr (self): 
return '<Post {}>'.format(self.body) 


新 的 “Post" 类 表示 用 户 发 表 的 动态 。 timestamp 字段 将 被 编 入 索引 ， 如 果 你 想 按时 间 顺 序 检索 
用 户 动态 ， 这 将 非常 有 用 。 我 还 为 其 添加 了 一 个 default 参数 ， 并 传 入 

了 datetime.utcnow 函数 。 当 你 将 一 个 函 on > SQLAIchemy 会 将 该 字段 设置 
为 调用 该 函数 的 值 (请 注意 ， 在 utcnow 之 后 我 没有 包 Z O ， 所 以 我 传递 函 数 本 身 ， 而 不 是 

调用 它 的 结果 ) 。 通常 l AMAM PEMUT AMNA RAAE 这 可 以 确保 你 使 用 
统一 的 时 间 戳 ， 无 论 用 户 位 于 何 处 ， 这 些 时 间 改 会 在 显示 时 转换 为 用 户 的 当地 时 间 。 


user_id 字段 被 初始 化 为 user.id 的 外 键 ， 这 意味 着 它 引 用 了 来 自用 户 表 的 id 值 。 本 处 

的 user 是 数据 库 表 的 名 称 ， re 动 设 置 类 名 为 小 写 来 作为 对 应 表 的 名 称 。 
User 类 有 一 个 新 的 posts 字段 ， 用 db.relationship 初始 化 。 这 不 是 实际 的 数据 库 字 段 ， 而 
是 用 户 和 其 动态 之 间 关 系 的 高 级 视图 ， 因 此 它 不 在 数据 库 图 表 中 。 对 于 一 对 多 关 

系 ， db.relationship 字段 通常 在 “一 "的 这 边 定义 ， 并 用 作 访 问 “ 多 ”的 便捷 方式 。 因 此 ， 如 果 
我 有 一 个 用 户 实例 u ， 表 达 式 u.posts 将 运行 一 个 数据 库 查 询 ， 返 回 该 用 户 发 表 过 的 所 有 动 
Š o db.relationship 的 第 一 个 参数 表示 代表 关 系 “ 多 ”的 类 ° backref 参数 定义 了 代表 “多 ”的 
类 的 实例 反 向 调用 “一 ”的 时 候 的 属性 名 称 S 这 将 会 为 用 户 动 态 添加 一 个 属性 post.author ， 调 
用 它 将 返回 给 该 用 户 动 态 的 用 户 实 例 。 lazy 参数 定义 了 这 种 关系 调用 的 数据 库 查 询 是 如 何 
执行 的 ， 这 个 我 会 在 后 面 讨论 。 不 要 觉得 这 些 细节 没什么 意思 ， 本 章 的 结尾 将 会 给 出 对 应 的 
ATS 


—BRELT RARE RELA RPAH E E tA 


(venv) $ flask db migrate -m "posts table" 
INFO [alembic.runtime.migration] Context impl SQLiteImpl. 
INFO [alembic.runtime.migration] Will assume non-transactional DDL. 
INFO [alembic.autogenerate.compare] Detected added table 'post' 
INFO [alembic.autogenerate.compare] Detected added index 'ix_post_timestamp' on '['ti 
mestamp']' 
Generating /home/miguel/microblog/migrations/versions/780739b227a7_posts_table.py .. 
. done 


并 将 这 个 迁移 应 用 到 数据 库 : 


(venv) $ flask db upgrade 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.runtime.migration] Running upgrade e517276bbic2 -> 780739b227a7, posts 
table 


如 果 你 对 项 目 使 用 了 版 本 控制 ， 记 得 将 新 的 迁移 脚本 添加 进去 并 提交 。 


演 时 刻 
经 历 了 一 个 漫长 的 过 程 来 定义 数据 库 ， 我 却 还 没 向 你 展示 它们 如 何 使 用 。 由 于 应 用 还 没有 任 
何 数据 库 逻 辑 ， 所 以 让 我 们 在 Python 解 释 器 中 来 使 用 以 便 熟 悉 它 。 立 即 运行 python 命令 来 
启动 Python (在 启动 解释 器 之 前 ， 确 保 您 的 虚拟 环境 已 被 激活 ) o 


进入 Python 交互 式 环境 后 ， 寻 入 数据 库 实例 和 模型 : 


>>> from app import db 
>>> from app.models import User, Post 


开始 阶段 ， 创 建 一 个 新 用 户 : 


>>> u = User(username='john', email='john@example.com' ) 
>>> db.session.add(u) 
>>> db.session.commit() 


对 数据 库 的 更 改 是 在 会 话 的 上 下 文中 完成 的 ， 你 可 以 通过 db.session 进行 访问 验证 。 允许 在 
会 话 中 累积 多 个 更 改 ， 一 旦 所 有 更 改 都 被 注册 ， 你 可 以 发 出 一 个 指令 db.session.commit() 来 
以 原子 方式 写 入 所 有 更 改 。 如 果 在 会 话 执行 的 任何 时 候 出 现 错误 ， 调 

用 db.session.rollback() 会 中 止 会 话 并 删除 存储 在 其 中 的 所 有 更 改 。 要 记 住 的 重要 一 点 是 ， 
只 有 在 调用 db.session.commit() 时 才 会 将 更 改写 入 数据 库 。 会话 可 以 保证 数据 库 永远 不 会 处 
于 不 一 致 的 状态 。 


添加 另 一 个 用 户 : 


>>> u = User(username='susan', email='susan@example.com' ) 
>>> db.session.add(u) 
>>> db.session.commit() 


数据 库 执行 返回 所 有 用 户 的 查询 : 


>>> users = User.query.all() 
>>> users 
[<User john>, <User susan>] 
>>> for u in users: 

print(u.id, u.username) 


1 john 
2 susan 


所 有 模型 都 有 一 个 query 属性 ， 它 是 运行 数据 库 查询 的 入 口 。 最 基本 的 查询 就 是 返回 该 类 的 
所 有 元 素 ， 它 被 适当 地 命名 为 alo 。 请 注意 ， 添 加 这 些 用 户 时 ， 它 们 的 id 字段 依次 自动 
设置 为 1 和 2。 


另外 一 种 查询 方式 是 ， 如 果 你 知道 用 户 的 id ， 可 以 用 以 下 方式 直接 获取 用 户 实例 : 


>>> u = User.query.get(1) 
>>> U 
<User john> 


现在 添加 一 条 用 户 动态 : 


>>> u User.query.get(1) 

>>> p Post(body='my first post!', author=u) 
>>> db.session.add(p) 

>>> db.session.commit() 


我 不 需要 为 timestamp 字段 设置 一 个 值 ， 因 为 这 个 字段 有 一 个 默认 值 ， 你 可 以 在 模型 定义 中 
看 到 。 那 么 user_id 字段 呢 ? 回想 一 下 ， 我 在 user 类 中 创建 的 db.relationship 为 用 户 添 加 
了 posts 属性 ， 并 为 用 户 动态 添加 了 author 属性 。 我 使 用 author 虚拟 字段 来 调用 其 作者 ， 
而 不 必 通 过 用 户 ID 来 处 理 。 SQLAIchemy 在 这 方面 非常 出 色 ， 因 为 它 提 供 了 对 关系 和 外 键 的 
高 级 抽象 。 


为 了 完成 演示 ， 让 我 们 看 看 另外 的 数据 库 查询 案例 : 


>>> # get all posts written by a user 
>>> u = User.query.get(1) 

>>> u 

<User john> 

>>> posts = u.posts.all() 

>>> posts 

[<Post my first post!>] 


>>> # same, but with a user that has no posts 
>>> u = User.query.get(2) 
>>> U 


<User susan> 
>>> u.posts.all() 


[] 


>>> # print post author and body for all posts 
>>> posts = Post.query.all() 
>>> for p in posts: 

print(p.id, p.author.username, p.body) 


1 john my first post! 
# get all users in reverse alphabetical order 


>>> User.query.order_by(User.username.desc()).all() 
[<User susan>, <User john>] 


Flask-SQLAIchemy 文 档 是 学 习 其 对 应 操作 的 最 好 去 处 。 


学 完 本 节 内 容 ’ 我 们 需要 清除 > 这 些 测试 用 户 和 用 户 动态 S$? 以 便 保 持 数据 整洁 和 为 下 一 章 做 好 
准备 : 
>>> users = User.query.all() 
>>> for u in users: 
db.session.delete(u) 
>>> posts = Post.query.all() 
>>> for p in posts: 


db.session.delete(p) 


>>> db.session.commit() 


Shell_E FX 
还 记得 上 一 节 的 局 启动 Python 解释 器 之 后 你 做 过 什么 吗 ? 第 一 件 事 是 运行 两 条 导入 语 钉 : 


>>> from app import db 
>>> from app.models import User, Post 


ee ee ed 
flask shell 命令 是 flask 命令 集中 的 另 一 个 非常 有 用 的 工具 。 shell 命令 是 Flask 在 

继 run 之 后 的 实现 第 二 个 "核心 "命令 。 这 个 命令 的 目的 是 在 应 用 的 ony 动 一 个 Python 
解释 器 。 这 意味 着 什么 ? 看 下 面 的 例子 


(venv) $ python 

>>> app 

Traceback (most recent call last): 
File "<stdin>", line 1, in <module> 

NameError: name 'app' is not defined 

>>> 


(venv) $ flask shell 
>>> app 
<Flask ‘app'> 


使 用 常规 的 解释 器 会 话 时 ， 除 非 明确 地 被 导入 ， 否 则 app 对 象 是 未 知 的 ， 但 是 当 使 
用 flask shell 时 ， 该 命令 预先 导入 应 用 实例 。 flask shell 的 绝妙 之 处 不 在 于 它 预先 导入 
了 app ;而 是 你 可 以 配置 一 个 “shell 上 下 文 "， 也 就 是 可 以 预先 导入 一 份 对 象 列表 。 


在 microblog.py 中 实现 一 个 亟 数 ， 它 通过 添加 数据 库 实例 和 模型 来 创建 了 一 个 shell 上 下 文 环 


境 : 


from app import app, db 
from app.models import User, Post 


@app.shell_context_processor 
def make_shell_context(): 
return {'db': db, 'User': User, 'Post': Post} 


app.shell_context_processor 装饰 器 将 该 函数 注册 为 一 个 shell 上 下 文 函 数 。 

当 flask shell 命令 运行 时 ， 它 会 调用 这 个 函数 并 在 shell 会 话 中 注册 它 返 回 的 项 目 。 函数 返 
回 一 个 字典 而 不 是 一 个 列表 ， 原 因 是 对 于 每 个 项 目 ， 你 必须 通过 字典 的 键 提供 一 个 名 称 以 便 
在 shell 中 被 调用 。 


在 添加 shell 上 下 文 处 理 器 函数 后 ， 你 无 需 导 入 就 可 以 使 用 数据 库 实例 : 


(venv) $ flask shell 

>>> db 

<SQLAlchemy engine=sqlite:////Users/migu7781/Documents/dev/flask/microblog2/app.db> 
>>> User 

<class 'app.models.User'> 

>>> Post 

<class 'app.models.Post'> 


本 文 翻 译 自 The Flask Mega-Tutorial Part V: User Logins 
这 是 Flask Mega-Tutorial 系 列 的 第 五 部 分 ， 我 将 告诉 你 如 何 创建 一 个 用 户 登 录 子 系统 。 


你 在 第 三 草 中 学 会 了 如 何 创建 用 户 登 录 表 单 ， 在 第 四 章 中 学 会 了 运用 数据 库 。 本 章 将 教 你 如 
何 结合 这 两 章 的 主题 来 创建 一 个 简单 的 用 户 登 录 系 统 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 
Fe A 
BB AD Mes Ar 


在 第 四 齐 中 ， 用 户 模型 设置 了 一 个 password_hash 字段 ， 到 目前 为 止 还 没有 被 使 用 到 。 

字段 的 目的 是 保存 用 户 密 码 的 哈 希 值 ， 并 用 于 验证 用 户 在 登录 过 程 中 输入 的 密码 。 ee 
KN ELMA-TRRWEM? RAKES RKC? FL? LAARNI A AA 
能 完备 加 密 库 存在 了 。 


其 中 一 个 实现 密码 哈 希 的 包 是 Werkzeug， 当 安装 Flask 时 ， 你 可 能 会 在 pip 的 输出 中 看 到 这 
包 ， 因 为 它 是 Flask 的 一 个 核心 依赖 项 。 所 以 ，Werkzeug 已 经 安 你 的 虚拟 环境 中 。 i 
Python shell 会 话 演示 了 如 何 哈 希 密码 : 


>>> from werkzeug.security import generate password_hash 

>>> hash = generate_password_hash('foobar' ) 

>>> hash 

"pbkdf2:sha256 : 50000$vT9FKZM8$04dfa35c6476acf7e788a1b5b3c35e217c78dc04539d295F011F 01F1 
8cd2175F ' 


这 个 例子 中 ， 通 过 一 系列 已 知 没有 反 向 操作 的 加 蜜 操作， 将 密码 foobar 转换 成 一 个 长 编码 
符 囊 ， 这 意味 着 获得 密码 哈 希 值 的 人 将 无 法 使 用 ie menus 密码 。 作为 一 个 附加 手段 ， 

次 哈 希 相同 的 密码 ， 你 将 得 到 不 同 的 结果 ， 所 以 这 使 得 无 法 通过 查看 它们 的 哈 希 值 来 确定 

用 户 是 否 具有 相同 的 密码 。 


mw 4) 
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给 证 过 程 使 用 Werkzeug 的 第 二 个 函数 来 完成 ， 如 下 所 示 : 


>>> from werkzeug.security import check_password_hash 
>>> check_password_hash(hash, 'foobar') 

True 

>>> check_password_hash(hash, 'barfoo') 

False 


向 验证 函数 传 入 之 前 生成 的 密码 哈 希 值 以 及 用 户 在 登录 时 输入 的 密码 ， 如 果 用 户 提 供 的 密码 
执行 哈 希 过 程 后 与 存储 的 哈 希 值 匹 配 ， 则 返回 true > SMR False ° 


整个 密码 哈 希 逻辑 可 以 在 用 户 模型 中 实现 为 两 个 新 的 方法 : 


from werkzeug.security import generate_password_hash, check_password_hash 
GA nay 


class User(db.Model): 
# oaia 


def set_password(self, password): 
self .password_hash = generate_password_hash(password) 


def check_password(self, password): 
return check_password_hash(self.password_hash, password) 


使 用 这 两 种 方法 ， 用 户 对 象 现 在 可 以 在 无 需 持 久 化 存储 原始 密码 的 条 件 下 执行 安全 的 密码 验 
证 。 以 下 是 这 些 新 方法 的 示例 用 法 : 


>>> u = User(username='susan', email='susan@example.com' ) 
>>> u.set_password('mypassword' ) 

>>> u.check_password( 'anotherpassword' ) 

False 

>>> u.check_password( 'mypassword' ) 

True 


Flask-Login 简介 


在 本 章 中 ， 我 将 向 你 介绍 一 个 非常 受 欢 迎 的 Flask 插 件 Flask-Login。 该 插件 管理 用 户 登录 状 
态 ， 以 便 用 户 可 以 登录 到 应 用 ， 然 后 用 户 在 导航 到 该 应 用 的 其 他 页 面 时 ， 应 用 会 “记得 "该 用 户 

已 经 登录 。 它 还 提供 了 “ 记 住 我 "的 功能 ， 允 许 用 户 在 关闭 浏览 器 窗口 后 再 次 访问 应 用 时 保持 登 
录 状 态 。 可 以 先 在 你 的 虚拟 环境 中 安装 Flask-Login Pi 


(venv) $ pip install flask-login 


和 其 他 插件 一 样 ，Flask-Login 需 要 在 app/ init py 中 的 应 用 实例 之 后 被 创建 和 初始 化 。 该 插件 
初始 化 代码 如 下 


# i... 
from flask_login import LoginManager 


app = Flask(__name_ ) 
#.. 
login = = LoginManager (app) 


# ... 


为 Flask-Login 准 备用 户 模型 


Flask-Login 插 件 需要 在 用 户 模型 上 实现 菜 些 属性 和 方法 。 这 种 做 法 很 棒 ， 因 为 只 要 将 这 些 必 
需 项 添加 到 模型 中 ，Flask-Login 就 没有 其 他 依赖 了 ， 它 就 可 以 与 基于 任何 数据 库 系 统 的 用 户 
模型 一 起 工作 。 


必须 的 四 项 如 下 : 


e is_authenticated : 一 个 用 来 表示 用 户 是 否 通 过 登录 认证 的 属性 ， 用 True 和 False 表 
示 。 

e is active: 如 果 用 户 账户 是 活跃 的 ， 那 么 这 个 属性 是 True ， 否 则 就 是 False (EH 

: 活路 用 户 的 定义 是 该 用 户 的 登录 状态 是 否 通 过 用 户 名 密码 登录 ， 通 过 “ 记 住 我 "功能 保 
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@ is_anonymous : 常规 用 户 的 该 属性 是 False ， 对 特定 的 匿名 用 户 是 True ° 

e get_id() :返回 用 户 的 唯一 id 的 方法 ， 返 回 值 类 型 是 字符 串 (Python 2 下 返回 unicode 字 符 
串 ). 


我 可 以 很 容易 地 实现 这 四 个 属性 或 方法 ， 但 是 由 于 它们 是 相当 通用 的 ， 因 此 Flask-Login 提 供 
了 一 个 叫做 UserMixin 的 mixin 类 来 将 它们 归纳 其 中 。 下面 演 示 了 如 何 将 mixin 类 添加 到 模型 
中 : 

# ,,， 

from flask_login import UserMixin 


class User(UserMixin, db.Model): 
Tigress 
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用 户 会 话 是 Flask 分 配给 每 个 连接 到 应 用 的 用 户 的 存储 空间 ，Flask-Login 通 过 在 用 户 会 话 中 存 
储 其 唯一 标识 符 来 跟踪 登录 用 户 。 每 当 已 登录 的 用 户 导 航 到 新 页 面 时 ，Flask-Login 将 从 会 话 
中 检索 用 户 的 ID， 然 后 将 该 用 户 实例 加 载 到 内 存 中 。 


因为 数据 库 对 Flask-Login 透 明 ， 所 以 需要 应 用 来 辅助 加 载 用 户 。 基 于 此 ， 插 件 期 望 应 用 配置 
一 个 用 户 加 载 函 数 ， 可 以 调用 该 函数 来 加 载 给 定 |D 的 用 户 。 该 功能 可 以 添加 到 app/models.py 
模块 中 : 


from app import login 
# a, 


@login.user_loader 
def load_user(id): 
return User.query.get(int(id) ) 


使 用 Flask-Login 的 @login.user_loader 装饰 器 来 为 用 户 加 载 功能 注册 函数 。 Flask-Login 将 字 


符 串 类 型 的 参数 id 传 入 用 户 加 载 函 数 ， 因 此 使 用 数字 ID 的 数据 库 需 要 如 上 所 示 地 将 字符 串 转 
换 为 整数 。 


用 户 登 入 


让 我 们 回顾 一 下 登录 视图 函数 ， 它 实现 了 一 个 模拟 登录 ， 只 发 出 一 个 flash() 消息 。 现 在 ， 
应 用 可 以 访问 用 户 数据 ， 并 知道 如 何 生成 和 验证 密码 哈 希 值 ， 该 视图 函数 就 可 以 完工 了 。 


# ,,， 
from flask_login import current_user, login_user 
from app.models import User 


# ... 


@app.route('/login', methods=['GET', 'POST']) 
def login(): 
if current_user.is_authenticated: 
return redirect(url_for('index')) 
form = LoginForm() 
if form.validate_on_submit(): 
user = User.query.filter_by(username=form.username.data).first() 
if user is None or not user.check_password(form.password.data): 
flash('Invalid username or password') 
return redirect(url_for('login')) 
login_user(user, remember=form.remember_me. data) 
return redirect(url_for('index') ) 
return render_template('login.html', title='Sign In', form=form) 


login() 函数 中 的 前 两 行 处 理 一 个 非 预期 的 情况 : 假设 用 户 已 经 登录 ， 却 导航 到 应 用 的 /login 
URL。 显然 这 是 一 个 不 可 能 允许 的 错误 场景 。 current_user 变量 来 自 Flask-Login， 可 以 在 
处 理 过程 中 的 任何 时 候 调 用 以 获取 用 户 对 象 。 这 个 变量 的 值 可 以 是 数据 库 中 的 一 个 用 户 对 四 
(Flask-Login 通 过 我 上 面 提供 的 用 户 加 载 函 数 回 调 读 取 ) ， 或 者 如 果 用 户 还 没有 登录 ， 则 是 
一 个 特殊 的 匿名 用 户 对 象 。 还 记得 那些 Flask-Login 必 须 的 用 户 对 象 属性 ? 其 中 之 一 

是 is_authenticated ， 它 可 以 方便 地 检查 用 户 是 否 登 录 。 当 用 户 已 经 登录 ， 我 只 需要 重 定 向 
到 主页 。 


相 比 之 前 的 调用 flash() 显示 消息 模拟 登录 ， 现 在 我 可 以 中 实地 登录 用 户 。 第 一 步 是 从 数据 
库 加 载 用 户 。 利用 表单 提交 的 username， 我 可 以 查询 数据 库 以 找到 用 户 。 为 此 ， 我 使 用 了 
SQLAIchemy #74 * #4) filter_ by() 方法 。 filter_by() 的 结果 是 一 个 只 包含 具有 匹配 用 户 
名 的 对 象 的 查询 结果 集 。 因为 我 知道 查询 用 户 的 结果 只 可 能 是 有 或 者 没有 ， 所 以 我 通过 调 
用 first() 来 完成 查询 ， 如 果 存 在 则 返回 用 户 对 象 ;如 果 不 存 在 则 返回 None。 在 第 四 章 中 ， 
你 已 经 看 到 当 你 在 查询 中 调用 alo 方法 时 ， 将 执行 该 查询 并 获得 与 该 查询 匹配 的 所 有 结果 
的 列表 。 当 你 只 需要 一 个 结果 时 ， 通 常 使 用 first() 方法 。 


如 果 使 用 提供 的 用 户 名 执行 查询 并 成 功 匹 配 ， 我 可 以 接 下 来 通过 调用 上 面 定义 

的 check_password() 方法 来 检查 表单 中 随 附 的 密码 是 否 有 效 。 密码 验证 时 ， 将 验证 存储 在 数 
据 库 中 的 密码 哈 希 值 与 表单 中 输入 的 密码 的 哈 希 值 是 否 匹 配 。 所 以 ， 现 在 我 有 两 个 可 能 的 错 
误 情况 : 用 户 名 可 能 是 无 效 的 ， 或 者 用 户 密码 是 错误 的 。 在 这 两 种 情况 下 ， 我 都 会 闪现 一 条 
消息 ， 然 后 重 定向 到 登录 页 面 ， 以 便 用 户 可 以 再 次 尝试 。 


如 果 用 户 名 和 密码 都 是 正确 的 ， 那 么 我 调用 来 自 Flask-Login 的 login_user() 函数 。 该 函数 会 
将 用 户 登 录 状 态 注册 为 已 登录 ， 这 意味 着 用 户 导 航 到 任何 未 来 的 页 面 时 ， 应 用 都 会 将 用 户 实 


例 赋值 给 current_user 变量 。 


然后 ， 只 需 将 新 登录 的 用 户 重 定向 到 主页 ， 我 就 完成 了 整个 登录 过 程 。 
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提供 一 个 用 户 登 出 的 途径 也 是 必须 的 ， 我 将 会 通过 Flask-Login 的 logout_user() 函数 来 实现 。 
其 视图 函数 代码 如 下 : 
4 


from flask_login import logout_user 
# wn. 


@app.route('/logout' ) 
def logout(): 
logout_user() 
return redirect(url_for('index')) 


为 了 给 用 户 暴露 登 出 链接 ， 我 会 在 导航 栏 上 实现 当 用 户 登 录 之 后 ， 登 录 链 接 自动 转换 成 登 出 
链接 。 修 改 base.html 模 板 的 导航 栏 部 分 后 ， 代 码 如 下 : 


<div> 
Microblog: 
<a href="{{ url_for('index') }}">Home</a> 
{% if current_user.is_anonymous %} 
<a href="{{ url_for('login') }}">Login</a> 
{% else %} 
<a href="{{ url_for('logout') }}">Logout</a> 
{% endif %} 
</div> 


用 户 实例 的 is_anonymous 属性 是 在 其 模型 继承 UserMixin 类 后 Flask-Login 添 加 的 ， 表 达 
式 current_user.is_anonymous 仅 当 用 户 未 登录 时 的 值 是 True ° 
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Flask-Login 提 供 了 一 个 非常 有 用 的 功能 用 户 在 查看 应 用 的 特定 页 面 之 前 登录 。 如 果 
未 登录 的 用 户 尝试 查看 受 保 护 的 页 面 ，Flask-Login 将 自动 将 用 户 重 定向 到 登录 表单 ， 并 且 只 
有 在 登录 成 功 后 才 重 定向 到 用 户 想 查看 的 页 面 





为 了 实现 这 个 功能 ，Flask-Login 需 要 知道 哪个 视图 函数 用 于 处 理 登 录 认 证 。 在 app/init.py 中 
添加 代码 如 下 : 


# wn, 
login = LoginManager (app) 
login.login_view = 'login' 


上 面 的 'login' 值 是 登录 视图 函数 (endpoint) 名 ， 换 多 话说 该 名 称 可 用 于 url_for() BAAN 
参数 并 返回 对 应 的 URL。 


Flask-Login 使 用 名 为 @login_required 的 装饰 器 来 拒绝 匿名 用 户 的 访问 以 保护 某 个 视图 函数 。 
当 你 将 此 装饰 器 添加 到 位 于 @app.route 装饰 器 下 面 的 视图 元 数 上 时 ， 该 函数 将 受到 保护 ， 不 
允许 未 经 身份 验证 的 用 户 访问 。 以 下 是 该 装饰 器 如 何 应 用 于 应 用 的 主页 视图 芳 数 的 案例 : 


from flask_login import login_required 


@app.route('/') 
@app.route('/index' ) 
@login_required 
def index(): 
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剩 下 的 就 是 实现 登录 成 功 之 后 自 定 重 定向 回 到 用 户 之 前 想 要 访问 的 页 面 。 当 一 个 没有 登录 的 
用 户 访问 被 @login_required 装饰 器 保护 的 视图 函数 时 ， 装 饰 器 将 重 定向 到 登录 页 面 ， 不 过 ， 
它 将 在 这 个 重 定向 中 包含 一 些 额 外 的 信息 以 便 登 录 后 的 回转 。 例如， 如 果 用 户 导 航 

al/index > IRZ @login_required 装饰 器 将 拦截 请 求 并 以 重 定向 到 Mogjnm 来 响应 ， 但 是 它 会 添加 
一 个 查询 字符 囊 参 数 来 丰富 这 个 URL， 如 /login?next=/index。 原 始 URL 设 置 了 next 查询 字 

符 串 参数 后 ， 应 用 就 可 以 在 登录 后 使 用 它 来 重 定向 。 


下 面 是 一 段 代码 ， 展 示 了 如 何 读 取 和 处 理 next 查询 字符 串 参 数 : 


from flask import request 
from werkzeug.urls import url_parse 


@app.route('/login', methods=['GET', 'POST']) 
def noe 


= form. validate_on_submit(): 

user = User.query.filter_by(username=form.username.data).first() 

if user is None or not user.check_password(form.password.data): 
flash('Invalid username or password') 
return redirect(url_for('login' ) ) 

login_user(user, remember=form. remember_me.data) 

next_page = request.args.get('next') 

if not next_page or url_parse(next_page).netloc != '': 
next_page = url_for('index') 

return redirect (next_page) 


在 用 户 通过 调用 Flask-Login 的 login_user() 函数 登录 后 ， 应 用 获取 了 next 查询 字符 串 参 数 
的 值 。Flask 提 供 一 个 request 变量 ， 其 中 包含 客户 端 随 请 求 发 送 的 所 有 信息 。 特别 

是 request.args 属性 ， 可 用 友好 的 字典 格式 暴露 查 询 字 符 串 的 内 容 。 实际 上 有 三 种 可 能 的 情 
况 需要 考虑 ， 以 确定 成 功 登 录 后 重 定 向 的 位 置 


o 如 果 登 录 URL 中 不 含 next 参数 ， 那 么 将 会 重 定向 到 本 应 用 的 主页 。 

e 如 果 登 录 URL 中 包含 next 参数 ， 其 值 是 一 个 相对 路 径 ( 换 名 话说， 该 URL 不 含 域名 信 
息 ) ， 那 么 将 会 重 定向 到 本 应 用 的 这 个 相对 路 径 

o 如 果 登 录 URL 中 包含 next 参数 ， 其 值 是 一 个 包含 域名 的 完整 URL， 那 么 重 定向 到 本 应 用 
的 主页 。 


前 两 种 情况 很 好 理解 ， 第 三 种 情况 是 为 了 使 应 用 更 安全 。 攻击 者 可 以 在 next 参数 中 插入 一 
个 指向 恶意 站 点 的 URL， 因 此 应 用 仅 在 重 定向 URL 是 相对 路 径 时 才 执 行 重 定向 ， 这 可 确保 重 
定向 与 应 用 保持 在 同一 站 点 中 。 为 了 确定 URL 是 相对 的 还 是 绝对 的 ， 我 使 用 Werkzeug 

的 url_parse() 函数 解析 ? 然后 检查 netloc 属性 是 否 被 设置 。 


在 模板 中 显示 已 登录 的 用 户 


你 还 记得 在 实现 用 户 子 系统 之 前 的 第 二 草 中 ， 我 创建 了 一 个 模拟 的 用 户 来 帮助 我 设计 主页 的 
事情 吗 ? 现在 ， 应 用 实现 了 申 正 的 用 户 ， 我 就 可 以 删除 模拟 用 户 了 。 取 而 代 之 ， 我 会 在 模板 
中 使 用 Flask-Login 的 current_user 


{% extends "base.html" %} 


{% block content %} 
<hi>Hi, {{ current_user.username }}!</h1i> 
{% for post in posts %} 
<div><p>{{ post.author.username }} says: <b>{{ post.body }}</b></p></div> 
{% endfor %} 
{% endblock %} 


并 且 我 可 以 在 视图 函数 传 入 泻 染 模 板 函 数 的 参数 中 删除 user 了 : 


@app.route('/') 
@app.route('/index' ) 
def index(): 
# i... 
return render_template("index.html", title='Home Page', posts=posts) 


这 正 是 测试 登录 和 注销 功能 运作 机 制 的 好 时 机 。 由 于 仍然 没有 用 户 注 册 功 能 ， 所 以 添加 用 户 
到 数据 库 的 唯一 方法 是 通过 Python shell 执 行 ， 所 以 运行 flask shell 并 输入 以 下 命令 来 注册 
AP: 


>>> u = User(username='susan', email='susan@example.com') 
>>> u.set_password('cat') 

>>> db.session.add(u) 

>>> db.session.commit() 


如 果 启 动 应 用 并 党 试 访问 http:/Nlocalhost:5000/ 或 http:/localhost:5000/index， 会 立即 重 定向 到 
登录 页 面 。 在 使 用 之 前 添加 到 数据 库 的 凭据 登录 后 ， 就 会 跳 转 回 到 之 前 访问 的 页 面 ， 并 看 到 
其 中 的 个 性 化 欢迎 。 
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本 章 要 构建 的 最 后 一 项 功能 是 注册 表单 ， 以 便 用 户 可 以 通过 Web 表 单 进行 注册 。 让 我 们 
在 app/forms.py 中 创建 Web 表 单 类 来 开始 吧 : 


from flask_wtf import FlaskForm 

from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import ValidationError, DataRequired, Email, EqualTo 
from app.models import User 


# ... 


class RegistrationForm(FlaskForm): 
username = StringField('Username', validators=[DataRequired()]) 
email = StringField('Email', validators=[DataRequired(), Email()]) 
password = PasswordField('Password', validators=[DataRequired()]) 
password2 = PasswordField( 
"Repeat Password', validators=[DataRequired(), EqualTo('password')]) 
submit = SubmitField('Register' ) 


def validate_username(self, username): 
user = User.query.filter_by(username=username.data).first() 
if user is not None: 
raise ValidationError('Please use a different username. ') 


def validate_email(self, email): 
user = User.query.filter_by(email=email.data).first() 
if user is not None: 
raise ValidationError('Please use a different email address.') 


代码 中 与 验证 相关 的 几 处 相当 有 趣 。 首 先 ， 对 于 email 字段 ， 我 在 dataRequired 之 后 添加 了 
第 二 个 验证 器 ， 名 为 Email 。 这 个 来 自 WTForms 的 另 一 个 验证 器 将 确保 用 户 在 此 字段 中 键入 
的 内 容 与 电子 邮件 地 址 的 结构 相 匹配 。 


由 于 这 是 一 个 注册 表单 ， 习 惯 上 要 求 用 户 输 入 密码 两 次 ， 以 减少 输入 错误 的 风险 。 出 于 这 个 
原因 ， 我 提供 了 password 和 password2 字段 。 第 二 个 password 字 段 使 用 另 一 个 名 
为 EqualTo 的 验证 器 ， 它 将 确保 其 值 与 第 一 个 password 字 段 的 值 相同 。 


我 还 为 这 个 类 添加 了 两 个 方法 ， 名 为 validate _username() 和 validate email() ° 当 添 加 任何 
匹配 模式 validate_ <field_name> 的 方法 时 ，VWTForms 将 这 些 方法 作为 自 定义 验证 器 ， 并 在 
已 设置 验证 器 之 后 调用 它们 。 本 处 ， 我 想 确保 用 户 输入 的 username 和 email 不 会 与 数据 库 中 
已 存在 的 数据 冲突 ， 所 以 这 两 个 方法 执行 数据 库 查 询 ， 并 期 望 结果 集 为 室 。 否则 ， 则 通 

过 validationError 触发 验证 错误 。 异常 中 作为 参数 的 消息 将 会 在 对 应 字段 旁边 显示 ， 以 供用 
户 查 看 。 


我 需要 一 个 HTML 模 板 以 便 在 网 页 上 显示 这 个 表单 ， 我 其 存储 在 app/templates/register.htm/ 文 
件 中 。 这 个 模板 的 构造 与 登录 表单 类 似 : 


{% extends "base.html" %} 


{% block content %} 


<hi>Register</hi> 

<form action="" method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.username.label }}<br> 
{{ form.username(size=32) }}<br> 
{% for error in form.username.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.email.label }}<br> 
{{ form.email(size=64) }}<br> 
{% for error in form.email.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.password.label }}<br> 
{{ form. password(size=32) }}<br> 
{% for error in form.password.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.password2.label }}<br> 
{{ form. password2(size=32) }}<br> 
{% for error in form.password2.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p>{{ form.submit() }}</p> 

</form> 
{% endblock %} 


登录 表单 模板 需要 在 其 表单 之 下 添加 一 个 链接 来 将 未 注册 的 用 户 引 寻 到 注册 页 面 : 


<p>New User? <a href="{{ url_for('register') }}">Click to Register!</a></p> 


最 后 ， 我 来 实现 处 理 用 户 注册 的 视图 函数 ， 存 储 在 app/routes.py 中 ， 代 码 如 下 : 


from app import db 
from app.forms import RegistrationForm 


# ... 


@app.route('/register', methods=['GET', 'POST']) 
def register(): 
if current_user.is_authenticated: 
return redirect(url_for('index')) 
form = RegistrationForm() 
if form.validate_on_submit(): 
user = User(username=form.username.data, email=form.email.data) 
user .set_password( form. password.data) 
db.session.add(user) 
db.session.commit() 
flash('Congratulations, you are now a registered user!') 
return redirect(url_for('login')) 
return render_template('register.html', title='Register', form=form) 


这 个 视图 函数 的 逻辑 也 是 一 目 了 然 ， 我 首先 确保 调用 这 个 路 由 的 用 户 没 有 登录 。 表 单 的 处 理 
方式 和 登录 的 方式 一 样 。 在 if validate_on_submit() 条 件 块 下 ， 完 成 的 逻辑 如 下 : 使 用 获取 
自 表单 的 Username、email 和 password 创 建 一 个 新 用 户 ， 将 其 写 入 数据 库 ， 然 后 重 定向 到 登 
录 页 面 以 便 用 户 登 录 。 


”| Register - Microblog 


€ C A © localhost:5000/register 





Microblog: Home Login 


Register 


Username 
john 


Email 
john@example.com 


Password 


Repeat Password 


[Field must be equal to password.] 


Register | 


精 雕 细 琢 之 后 ， 用 户 已 经 能 够 在 此 应 用 上 注册 帐户 ， 并 进行 登录 和 注销 。 请 确保 你 尝试 了 我 
在 注册 表单 中 添加 的 所 有 验证 功能 ， 以 便 更 好 地 了 解 其 工作 原理 。 我 将 在 未 来 的 章节 中 再 次 
更 新 用 户 认 证 子 系统 ， 以 增加 额外 的 功能 ， 比 如 允许 用 户 在 忘记 密码 的 情况 下 重 置 密码 。 不 
过 对 于 目前 的 应 用 来 讲 ， 这 已 经 无 碍 于 继续 构建 了 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part VI: Profile Page and Avatars 
这 是 Flask Mega-Tutorial 系 列 的 第 六 部 分 ， 我 将 告诉 你 如 何 创建 个 人 主页 。 


本 章 将 致力 于 为 应 用 添加 个 人 主页 。 个 人 主页 用 来 展示 用 户 的 相关 信息 ， 其 个 人 信息 由 本 人 
录入 。 我 将 为 你 展示 如 何 动 态 地 生成 每 个 用 户 的 主页 ， 并 提供 一 个 编辑 页 面 给 他 们 来 更 新 个 
人 信息 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


个 人 主页 
作为 创建 个 人 主页 的 第 一 步 ， 让 我 们 为 其 URL user 新 建 一 个 对 应 的 视图 函数 。 


@app.route('/user/<username>') 
@login_required 
def user(username): 
user = User.query.filter_by(username=username) .first_or_404() 
posts = [ 
{'author': user, 'body': 'Test post #1'}, 
{'author': user, 'body': 'Test post #2'} 


return render_template('user.html', user=user, posts=posts) 


我 用 来 装饰 该 视图 函数 的 @app.route 装饰 器 看 起 来 和 之 前 的 有 点 不 一 样 。 本 例 中 
AE 和 > &@EAVURL <username> 是 动态 的 。 当 一 个 路 由 包含 动态 组 件 时 ，Flask 将 接受 该 
分 URL 中 的 任何 文本 ， 并 将 以 实际 文本 作为 参数 调用 该 视图 函数 。 例 如， 如 果 客 户 端 浏览 
器 请 求 URL /user/susan ， 则 视图 函数 将 被 调用 ， 其 参数 username 被 设置 为 'susan' ° AA 
这 个 视图 函数 只 能 被 已 登录 的 用 户 访问 ， 所 以 我 添加 了 @login_required 装饰 器 。 


这 个 视图 函数 的 实现 相当 简单 。 我 首先 会 尝试 在 数据 库 中 以 用 户 名 来 查询 和 加 载 用 户 。 之 前 
你 见 过 通过 调用 allo 来 得 到 所 有 的 结果 的 查询 ， 或 是 调用 first() 来 得 到 结果 中 的 第 一 个 
或 者 结果 集 为 空 时 返回 None 的 查询 。 在 本 视图 函数 中 ， ee first() 的 变种 方法 ， 名 

A first_or_404() ， 当 有 结果 时 它 的 工作 方式 与 first() 完全 相同 ， 但 是 在 oil 吉 果 的 情况 
下 会 自动 发 送 404 error 给 客户 端 。 以 这 种 方式 执行 查询 ， 我 省 去 检查 用 户 是 否 返回 的 步 又， 

因为 当 用 户 名 不 存在 于 数据 库 中 时 ， 函 数 将 不 会 返回 ， 而 是 会 引发 404 异 常 


如 果 执 行 数 据 库 查询 没有 触发 404 错 误 ， 那 么 这 意味 着 找到 了 具有 给 定 用 户 名 的 用 户 。 HEF 
来 ， 我 为 这 个 用 户 初始 化 一 个 虚拟 的 用 户 动态 列表 ， 最 后 用 传 入 的 用 户 对 象 和 用 户 动 态 列 表 
泻 沫 一 个 新 的 USerhtnm/ 模 板 。 


USerhtm/ 模 板 如 下 所 示 : 


{% extends "base.html" %} 


{% block content %} 
<hi>User: {{ user.username }}</h1> 
<hr> 
{% for post in posts %} 
<p> 
{{ post.author.username }} says: <b>{{ post.body }}</b> 
</p> 
{% endfor %} 
{% endblock %} 


个 人 主页 虽然 已 经 完成 了 ， 但 是 网 站 上 却 没 有 一 个 入 口 链接 。 我 将 会 在 顶部 的 导航 栏 中 添加 
这 个 入 口 链接 ， 以 便 用 户 可 以 轻松 查看 自己 的 个 人 资料 : 


<div> 
Microblog: 
<a href="{{ url_for('index') }}">Home</a> 
{% if current_user.is_anonymous %} 
<a href="{{ url_for('login') }}">Login</a> 
{% else %} 
<a href="{{ url_for('user', username=current_user.username) }}">Profile</a> 
<a href="{{ url_for('logout') }}">Logout</a> 
{% endif %} 
</div> 


里 唯一 有 趣 的 变化 是 用 来 生成 链接 到 个 人 主页 的 url_for() 调用 。 由 于 个 人 主页 视图 函数 


oe 数 ， 所 以 url_for() Bade MEN A AFAA o h PaA YS 
前 登录 个 人 主页 的 链接 ， 我 可 以 使 用 Flask-Login 的 current_user 对 象 来 生成 正确 的 URL ° 


Welcome to Microblog 


一 
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User: susan 


susan says: Test post #1 


susan says: Test post #2 


尝试 点 击 顶 部 的 profile 链接 就 能 将 你 带 到 自己 的 个 人 主页 。 此 时 ， 虽 然 没 有 链接 来 访问 其 
他 用 户 的 主页 ， 但 是 如 果 要 访问 这 些 页 面 ， 则 可 以 在 浏览 器 的 地 址 栏 中 手动 输入 网 址 。 例 
如 ， 如 果 你 在 应 用 中 注册 了 名 为 “ohn” 的 用 户 ， 则 可 以 通过 在 地 址 栏 中 键入 http:// 


localhost:5000/user/jiohn 来 查看 该 用 户 的 个 人 主页 。 


头像 


我 相信 你 也 觉得 我 刚刚 建立 的 个 人 主页 非常 枯燥 乏味 。 为 了 使 它们 更 加 有 趣 ， 我 将 添加 用 户 
头像 。 与 其 在 服务 器 上 处 理 大 量 的 上 传 图 片 ， 我 将 使 用 Gravatar 为 所 有 用 户 提供 图 片 服务 。 


Gravatar 服 务 使 用 起 来 非常 简单 。 要 请 求 给 定 用 户 的 图 片 ， 使 用 格式 

为 htips:/Www.gravatar.com/avatar/ 的 URL 即 可 ， 其 中 <hash> 是 用 户 的 电子 邮件 地 址 的 MD5 
哈 希 值 。 在 下 面 ， 你 可 以 看 到 如 何 生 成 电子 邮件 为 john@example.com 的 用 户 的 Gravatar 
URL : 


>>> from hashlib import md5 
>>> 'https://www.gravatar.com/avatar/' + md5(b'john@example.com').hexdigest() 
"https: //www. gravatar .com/avatar/d4c74594d841139328695756648b6bd6' 


如 果 你 想 看 一 个 实际 的 例子 ， 我 自己 的 Gravatar URL 
是 https:/www.gravatar.com/avatar/729e26a2a2c7ff24a71958d4aa4e5f35。Gravatar 返 回 的 
图 片 如 下 : 





默认 情况 下 ， 返 回 的 图 像 大 小 是 80x80 像 素 ， 但 可 以 通过 向 URL 的 查询 字符 串 添加 s 参数 来 
请 求 不 同 大 小 的 图 片 。 例 如 ， 要 获得 我 自己 128x128 像 素 的 头像 ， 该 URL 
是 https:/www.gravatar.com/avatar/729e26a2a2c7ff24a71958d4aa4e5f35?s=128。 


另 一 个 可 传递 给 Gravatar 的 有 趣 和 参数 是 ad ， 它 让 Gravatar 为 没有 向 服务 注册 头像 的 用 户 提 供 


的 随机 头像 。 我 最 喜欢 的 随机 头像 类 型 是 "jdenticon”， 它 为 每 个 邮箱 都 返回 一 个 漂亮 且 不 重 
复 的 几何 设计 图 片 。 如 下 : 





请 注意 ， 一 些 Web 浏 览 器 插件 《如 Ghostery) 会 屏蔽 Gravatar 图 像 ， 因 为 它们 认为 
Automattic (Gravatar 服 务 的 所 有 者 ) 可 以 根据 你 发 送 的 获取 头像 的 请 求 来 判断 你 正在 访问 的 
网 站 。 如 果 在 浏览 器 中 看 不 到 头像 ， 你 在 排查 问题 的 时 候 可 以 考虑 以 下 是 否 在 浏览 器 中 安装 
了 此 类 插件 。 


由 于 头像 与 用 户 相 关联 ， 所 以 将 生成 头像 URL 的 逻辑 添加 到 用 户 模型 是 有 道理 的 。 


from hashlib import md5 
# ann 


class User(UserMixin, db.Model): 
大 本 本 本 
def avatar(self, size): 
digest = md5(self.email.lower().encode( 'utf-8')).hexdigest() 
return 'https://www. gravatar .com/avatar/{}?d=identicon&s={}' .format( 
digest, size) 


User 类 新 增 的 avatar() 方法 需要 传 入 需求 头像 的 像素 大 小 ， 并 返回 用 户头 像 图 片 的 URL 。 

对 于 没有 注册 头像 的 用 户 ， 将 生成 “identicon” 类 的 随机 图 片 。 为 了 生成 MD5 哈 希 值 ， 我 首先 
将 电子 邮件 转换 为 小 写 ， 因 为 这 是 Gravatar 服 务 所 要 求 的 。 然后， 因为 Python 中 的 MD5 的 参 
数 类 型 需要 是 字 节 而 不 是 字符 串 ， 所 以 在 将 字符 串 传 递 给 该 函数 之 前 ， 需 要 将 字符 串 编码 为 

字 节 。 


如 果 你 对 Gravatar 服 务 很 有 兴趣 ， 可 以 学 习 他 们 的 文档 。 


下 一 步 需 要 将 头像 图 片 插 入 到 个 人 主页 的 模板 中 : 


{% extends "base.html" %} 


{% block content %} 
<table> 
<tr valign="top"> 
<td><img src="{{ user.avatar(128) }}"></td> 
<td><hi>User: {{ user.username }}</hi></td> 
</tr> 
</table> 
<hr> 
{% for post in posts %} 
<p> 
{{ post.author.username }} says: <b>{{ post.body }}</b> 
</p> 
{% endfor %} 
{% endblock %} 


使 用 user 类 来 返回 头像 URL 的 好 处 是 ， 如 果 有 一 天 我 不 想 继 续 使 用 Gravatar 头 像 了 ， 我 可 以 
重 写 avatar() 方法 来 返回 其 他 头像 服务 网 站 的 URL， 所 有 的 模板 将 自动 显示 新 的 头像 。 


我 的 个 人 主页 的 顶部 有 一 个 不 错 的 大 头像 ， 不 止 如 此 ， 底 下 的 所 有 用 户 动 态 都 会 有 一 个 小 头 
像 。 对 于 个 人 主页 而 言 ， 所 有 的 头像 当然 都 是 对 应 用 户 的 。 我 将 会 在 主页 面 上 实现 每 个 用 户 
动态 都 用 其 作者 的 头像 来 装饰 ， 这 样 一 来 看 起 来 就 非常 棒 了 。 


为 了 显示 用 户 动态 的 头像 ， 我 只 需要 在 模板 中 进行 一 个 小 小 的 更 改 : 


{% extends "base.htm1" %} 


{% block content %} 
<table> 
<tr valign="top"> 
<td><img src="{{ user.avatar(128) }}"></td> 
<td><hi>User: {{ user.username }}</hi></td> 
</tr> 
</table> 
<hr> 
{% for post in posts %} 
<table> 
<tr valign="top"> 
<td><img src="{{ post.author.avatar(36) }}"></td> 
<td>{{ post.author.username }} says:<br>{{ post.body }}</td> 
</tr> 
</table> 
{% endfor %} 
{% endblock %} 


Welcome to Microblog x 
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User: susan 





y susan says: 
Test post #1 
ay susan says: 

Test post #2 


使 用 Jinja2 子 模板 


我 设计 的 个 人 主页 ， 使 用 头像 和 文字 组 合 的 方式 来 展示 了 用 户 动态 。 现 在 我 想 在 主页 也 使 用 
类 似 的 风格 来 布局 。 我 可 以 复制 /粘贴 来 处 理 用 户 动态 演 染 的 模板 部 分 ， 但 这 实际 上 并 不 理 
想 ， 因 为 之 后 如 果 我 想 要 对 此 布局 进行 更 改 ， 我 将 不 得 不 记 住 要 更 新 两 个 模板 。 


取而代之 ， 我 要 创建 一 个 只 浑 染 一 条 用 户 动态 的 子 模板 ， 然 后 在 USerhtrmj/ 和 jnaex.htrm/ 模 板 中 
引用 它 。 首先 ， 我 要 创建 这 个 只 有 一 条 用 户 动态 HTML 元 素 的 子 模板 。 我 将 其 命名 
A app/templates/_post.html> _ 前 级 只 是 一 个 命名 约定 ， 可 以 帮助 我 识别 哪些 模板 文件 是 子 


模板 。 


<table> 
<tr valign="top"> 
<td><img src="{{ post.author.avatar(36) }}"></td> 
<td>{{ post.author.username }} says:<br>{{ post.body }}</td> 
</tr> 
</table> 


我 在 USerhtm/ 模 板 中 使 用 了 Jinja2 的 include 语句 来 调用 该 子 模板 : 


{% extends "base.html" %} 


{% block content %} 
<table> 
<tr valign="top"> 
<td><img src="{{ user.avatar(128) }}"></td> 
<td><hi>User: {{ user.username }}</hi></td> 
</tr> 
</table> 
<hr> 
{% for post in posts %} 
{% include '_post.html' %} 
{% endfor %} 
{% endblock %} 


应 用 的 主页 还 没有 完善 ， 所 以 现在 我 不 打算 在 其 中 添加 这 个 功能 。 


更 多 有 趣 的 个 人 资料 


新 增 的 个 人 主页 存在 的 一 个 问题 是 ， 芮 正 显示 的 内 容 不 够 丰富 。 用 户 喜 欢 在 个 人 主页 上 展示 
他 们 的 相关 信息 ， 所 以 我 会 让 他 们 写 一 些 自我 介绍 并 在 这 里 展示 。 我 也 将 跟踪 每 个 用 户 最 后 
一 次 访问 该 网 站 的 时 间 ， 并 显示 在 他 们 的 个 人 主页 上 。 


为 了 支持 所 有 这 些 额外 的 信息 ， 首 先 需要 做 的 是 用 两 个 新 的 字段 扩展 数据 库 中 的 用 户 表 : 


class User(UserMixin, db.Model): 
# i... 
about_me = db.Column(db.String(140) ) 
last_seen = db.Column(db.DateTime, default=datetime.utcnow) 


每 次 数据 库 被 修改 时 ， 都 需要 生成 数据 库 迁 移 。 在 第 四 章 中 ， 我 向 你 展示 了 如 何 设 置 应 用 以 
通过 迁移 脚本 跟踪 数据 库 的 变更 。 现在 有 两 个 新 的 字段 我 想 添加 到 数据 库 中 ， 所 以 第 一 步 是 
生成 迁移 脚本 : 


(venv) $ flask db migrate -m "new fields in user model" 
INFO [alembic.runtime.migration] Context impl SQLiteImpl. 
INFO [alembic.runtime.migration] Will assume non-transactional DDL. 
INFO [alembic.autogenerate.compare] Detected added column ‘'user.about_me' 
INFO [alembic.autogenerate.compare] Detected added column 'user.last_seen' 
Generating /home/miguel/microblog/migrations/versions/37f06a334dbf_new_fields_in_use 
r_model.py ... done 





migrate 命令 的 输出 表示 一 切 正 确 运 行 ， 因 为 它 显 示 user 类 中 的 两 个 新 字段 已 被 检测 到 。 


(venv) $ flask db upgrade 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.runtime.migration] Running upgrade 780739b227a7 -> 37f06a334dbf, new fi 
elds in user model 


我 希望 你 认识 到 使 用 迁移 框架 是 多 么 有 用 。 数据 库 中 的 用 户 数 据 仍 然 存在 ， 迁 移 框 架 如 同 实 
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， 我 将 会 把 新 增 的 两 个 字段 增加 到 个 人 主页 中 : 


{% extends "base.html" %} 


{% block content %} 
<table> 
<tr valign="top"> 
<td><img src="{{ user.avatar(128) }}"></td> 
<td> 
<hi>User: {{ user.username }}</h1> 
{% if user.about_me %}<p>{{ user.about_me }}</p>{% endif %} 
{% if user.last_seen %}<p>Last seen on: {{ user.last_seen }}</p>{% end 
if %} 
</td> 
</tr> 
</table> 


{% endblock %} 


请 注意 ， 我 用 Jinja2 的 条 件 语句 来 封装 了 这 两 个 字段 ， 因 为 我 只 希望 它们 在 设置 后 才 可 见 。 目 
前 ， 所 有 用 户 的 这 两 个 字段 都 是 空 的 ， 所 以 如 果 现在 运行 应 用 ， 则 不 会 看 到 这 些 字段 。 


记录 用 户 的 最 后 访问 时 间 


让 我 们 从 更 容易 实现 的 last_seen 字段 开始 。 我 想 要 做 的 就 是 一 旦 某 个 用 户 向 服务 器 发 送 请 
求 ， 就 将 当前 时 间 写 入 到 这 个 字段 。 


做 非常 的 枯燥 乏味 。 在 视图 函数 处 理 请 求 之 


为 每 个 视图 函数 添加 更 新 这 个 字段 的 逻辑 ， 这 么 
分 常见 ， 因 此 Flask 提 供 了 一 个 内 置 功能 来 实现 


前 执行 一 段 简 单 的 代码 逻辑 在 Web 应 用 中 十 
它 。 解 决 方案 如 下 : 


from datetime import datetime 


@app.before_request 
def before_request(): 
if current_user.is_authenticated: 
current_user.last_seen = datetime.utcnow() 
db.session.commit() 


Flask ? 的 @before_request 装饰 器 注册 在 视图 函数 之 前 执行 的 BR Bx o 这 是 非常 有 用 的 ? 因为 

现在 我 可 以 在 一 处 地 方 编写 代码 ， 并 让 它 在 任何 视图 函数 之 前 被 执行 。 该 代码 简单 地 实现 了 

EE current_user 是 否 已 经 登录 ， 并 在 已 登录 的 情况 下 将 last_seen 字段 设置 为 当前 时 间 。 

我 之 前 提 到 过 ， 应 用 应 该 以 一 致 的 时 间 单 位 工作 ， 标 准 做 法 是 使 用 UTC 时 区 ， 使 用 系统 的 本 
地 时 间 不 是 一 个 好 主意 ， 因 为 如 果 那 么 的 话 ， 数 据 库 中 存储 的 时 间 取 决 于 你 的 时 区 。 最 后 一 

步 是 提交 数据 库 会 话 ， 以 便 将 上 面 所 做 的 更 改写 入 数据 库 。 如 果 你 想 知 道 为 什么 在 提交 之 前 
没有 db.session.add() ， 考 虑 在 引用 current_user 时 ，Flask-Login 将 调用 用 户 加 载 函 数 ， 该 
函数 将 运行 一 个 数据 库 查 询 并 将 目标 用 户 添 加 到 数据 库 会 话 中 。 所 以 你 可 以 在 这 个 函数 中 再 
次 添加 用 户 ， 但 是 这 不 是 必须 的 ， 因 为 它 已 经 在 那里 了 。 


如 果 在 进行 此 更 改 后 查看 你 的 个 人 主页 ， 则 会 看 到 “Last seen on” 行 ， 并 且 时 间 非 常 接近 当前 
时 间 。 如 果 你 离开 个 人 主页 ， 然 后 返回 ， 你 会 看 到 时 间 在 不 断 更 新 。 


事实 上 ， 我 在 存储 时 间 和 在 个 人 主页 显示 时 间 的 时 候 ， 使 用 的 都 是 UTC 时 区 。 除 此 之 外 ， 显 
示 的 时 间 格 式 也 可 能 不 是 你 所 预期 的 ， 因 为 实际 上 它 是 Python datetime 对 象 的 内 部 表示 。 现 
在 ， 我 不 会 操心 这 两 个 问题 ， 因 为 我 将 在 后 面 的 章节 中 讨论 在 Web 应 用 中 处 理 日 期 和 时 间 的 
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Microblog: Home Profile Logout 


User: susan 


Last seen on: 2017-09-14 18:50:44.707434 





co susan says: 
Test post #1 
ie, susan says: 

Test post #2 


个 人 资料 编辑 器 


我 还 需要 给 用 户 一 个 表单 ， 让 他 们 输入 一 些 个 人 资料 。 表单 将 允许 用 户 更 改 他 们 的 用 户 名 ， 
并 且 写 一 些 个 人 介绍 ， 以 存储 在 新 的 about_me 字段 中 。 让 我 们 开始 为 它 写 一 个 表单 类 吧 : 


from wtforms import StringField, TextAreaField, SubmitField 
from wtforms.validators import DataRequired, Length 


# i... 

class EditProfileForm(FlaskForm): 
username = StringField('Username', validators=[DataRequired()]) 
about_me = TextAreaField('About me', validators=[Length(min=0, max=140)]) 
submit = SubmitField('Submit' ) 


我 在 这 个 表单 中 使 用 了 一 个 新 的 字段 类 型 和 一 个 新 的 验证 器 。 对 于 “about_me" 字 段 ， 我 使 

用 TextAreaField ， 这 是 一 个 多 行 输入 文本 框 ， 用 户 可 以 在 其 中 输入 文本 。 为 了 验证 这 个 字 
段 的 长 度 ， 我 使 用 了 Length ， 它 将 确保 输入 的 文本 在 0 到 140 个 字符 之 间 ， 因 为 这 是 我 为 数据 
库 中 的 相应 字段 分 配 的 空间 。 


该 表单 的 浑 染 模板 代码 如 下 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Edit Profile</h1> 


<form action="" method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.username.label }}<br> 
{{ form.username(size=32) }}<br> 
{% for error in form.username.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.about_me.label }}<br> 
{{ form.about_me(cols=50, rows=4) }}<br> 
{% for error in form.about_me.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p>{{ form.submit() }}</p> 

</form> 
{% endblock %} 


最 后 一 步 ， 使 用 视图 函数 将 它们 结合 起 来 : 


from app.forms import EditProfileForm 


@app.route('/edit_profile', methods=['GET', 'POST']) 
@login_required 
def edit_profile(): 
form = EditProfileForm() 
if form.validate_on_submit(): 
current_user.username = form.username.data 
current_user.about_me = form.about_me.data 
db.session.commit() 
flash('Your changes have been saved.') 
return redirect(url_for('edit_profile')) 
elif request.method == 'GET': 
form.username.data = current_user.username 
form.about_me.data = current_user.about_me 
return render_template('edit_profile.html', title='Edit Profile', 
form=form) 


这 个 视图 函数 处 理 表单 的 方式 和 其 他 的 视图 函数 略 有 不 同 。 如 果 validate_on_submit() 返 

回 True ， 我 将 表单 中 的 数据 复制 到 用 户 对 象 中 ， 然 后 将 对 象 写 入 数据 库 。 但 是 

当 validate_on_submit() 返回 False 时 ， 可 能 是 由 于 两 个 不 同 的 原因 。 这 可 能 是 因为 浏览 器 
刚刚 发 送 了 一 个 GET 请 求 ， 我 需要 通过 提供 表单 模板 的 初始 版 本 来 响应 。 也 可 能 是 这 种 情 

况 ， 浏 览 器 发 送 带 有 表单 数据 的 post 请 求 ， 但 该 数据 中 的 某 些 内 容 无 效 。 对 于 该 表单 ， 我 需 
要 区 别 对 待 这 两 种 情况 。 当 第 一 次 请 求 表单 时 ， 我 用 存储 在 数据 库 中 的 数据 预 填充 字段 ， 所 
以 我 需要 做 与 提交 相反 的 事情 ， 那 就 是 将 存储 在 用 户 字 段 中 的 数据 移动 到 表单 中 ， 这 将 确保 
这 些 表单 字段 具有 用 户 的 当前 数据 。 但 在 验证 错误 的 情况 下 ， 我 不 想 写 任何 表单 字段 ， 因 为 
它们 已 经 由 WTForms 卉 充 了 。 为 了 区 分 这 两 种 情况 ， 我 需要 检查 request.method ， 如 果 它 
是 GET ， 这 是 初始 请 求 的 情况 ， 如 果 是 post 则 是 提交 表单 验证 失败 的 情况 。 


Edit Profile - Microblog X 


< CQ © localhost:5000/edit_prof.. Q fr 





Microblog: Home Profile Logout 


Edit Profile 


Username 


miguel 


About me 


|m the author of the Flask Mega-Tutorial you are now | 
| reading! 
| 





Submit | 


我 将 个 人 资料 编辑 页 面 的 链接 添加 到 个 人 主页 ， 以 便 用 户 使 用 : 


{% if user == current_user %} 
<p><a href="{{ url_for('edit_profile') }}">Edit your profile</a></p> 
{% endif %} 


请 注意 我 巧妙 使 用 的 条 件 ， 它 确保 在 查看 自己 的 个 人 主页 时 出 现 编辑 个 人 资料 的 链接 ， 而 在 
查看 其 他 人 的 个 人 主页 时 不 会 出 现 。 


\@l Welcome to Microblog 


一 





Microblog: Home Profile Logout 








User: miguel 


I'm the author of the Flask Mega-Tutorial you 
are now reading! 


Last seen on: 2017-09-14 19:39:00.120704 





Edit your profile 






miguel says: 
Test post #1 
miguel says: 
Test post #2 





本 文 翻 译 自 The Flask Mega-Tutorial Part VII: Error Handling 
这 是 Flask Mega-Tutorial 系 列 的 第 七 部 分 ， 我 将 告诉 你 如 何在 Flask 应 用 中 进行 错误 处 理 。 


本 章 将 暂停 为 microblog 应 用 开发 新 功能 ， 转 而 讨论 处 理 BUG 的 策略 ， 因 为 它们 总 是 无 处 不 
在 。 为 了 帮助 本 章 的 演示 ， 我 故意 在 第 六 章 新 增 的 代码 中 遗留 了 一 处 BUG。 在 继续 阅读 之 
前 ， 看 看 你 能 不 能 找到 它 ! 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 
Flask 中 的 错误 处 理 机 制 
在 Flask 应 用 中 爆发 错误 时 会 发 生 什么 ?了 得 到 答案 的 最 好 的 方法 就 是 亲身 体验 一 下 。 启动 应 
用 ， 并 确保 至 少 有 两 个 用 户 注册 ， 以 其 中 一 个 用 户 身 份 登录 ， 打 开 个 人 主页 并 单 击 “ 编 辑 " 链 


接 。 在 个 人 资料 编辑 器 中 ， 尝 试 将 用 户 名 更 改 为 已 经 注册 的 另 一 个 用 户 的 用 户 名 ，boom ! 
(爆炸 声 ) 这 将 带 来 一 个 可 怕 的 “Internal Server Error’ 页面 : 


500 Internal Server Error 
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Internal Server Error 


The server encountered an internal error and was unable to 
complete your request. Either the server is overloaded or 
there is an error in the application. 


如 果 你 查看 运行 应 用 的 终端 会 话 ， 将 看 到 stack trace (堆栈 跟踪 ) 。 堆栈 跟踪 在 调试 错误 时 
非常 有 用 ， 因 为 它们 显示 堆栈 中 调用 的 顺序 ， 一 直到 产生 错误 的 行 : 


(venv) $ flask run 
* Serving Flask app "microblog" 
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 
[2017-09-14 22:40:02,027] ERROR in app: Exception on /edit_profile [POST] 
Traceback (most recent call last): 
File "/home/miguel/microblog/venv/lib/python3.6/site-packages/sqlalchemy/engine/base 
.py", line 1182, in _execute_context 
context) 
File "/home/miguel/microblog/venv/lib/python3.6/site-packages/sqlalchemy/engine/defa 
ult.py", line 470, in do_execute 
cursor.execute(statement, parameters) 
sqlite3.IntegrityError: UNIQUE constraint failed: user.username 


堆栈 跟踪 指示 了 BUG 在 何 处 。 本 应 用 ue 户 更 改 用 户 名 ， 但 却 没 有 验证 所 选 的 新 用 
系统 中 已 有 的 其 他 用 户 有 没有 冲突 。 错误 来 自 SQLAIchemy， 它 尝试 将 新 的 用 户 名 写 
数据 库 ， 但 数据 库 拒 绝 了 它 ， 因 为 username 列 是 用 unique=True 定义 的 。 


值得 注意 的 是 ， 提 供给 用 户 的 错误 页 面 并 没有 提供 关于 错误 的 丰富 信息 ， 这 是 正确 的 做 法 。 
我 绝对 不 希望 用 户 知道 崩溃 是 由 数据 库 错误 引起 的 ， 或 者 我 正在 使 用 什么 数据 库 ， 或 者 是 我 
的 数据 库 中 的 一 些 表 和 字段 名 称 。 所 有 这 些 信息 都 应 该 对 外 保密 。 


但 是 也 有 一 些 不 尺 人 意 之 处 。 错 误 页 面 简陋 不 堪 ， 与 应 用 布局 不 匹配 。 终端 上 的 日 志 不 断 刷 
新 ， 导 致 重要 的 堆栈 跟踪 信息 被 淹没 ， 但 我 却 需 要 不 断 回顾 它 ， 以 免 有 漏网 之 鱼 。 当然 ， 我 
有 一 个 BUG 需要 修复 。 我 将 解决 所 有 的 这 些 问 题 ， 但 首先 ， 让 我 们 来 谈 谈 Flask 的 调试 模式 。 


调试 模式 


你 在 上 面 看 到 的 处 理 错误 的 方式 对 在 生产 服务 器 上 运行 的 系统 非常 有 用 。 如 果 出 现 错 误 ， 用 
PAS ARERR D (尽管 我 打算 使 这 个 错误 页 面 更 友好 ) ， 错 误 的 重要 细节 在 服 
务 器 进程 输出 或 存储 到 日 志文 件 中 。 


ies ea 用 时 ， 可 以 启用 调试 模式 ， 它 是 Flask 在 浏览 器 上 直接 运行 一 个 友好 调试 
模式 。 要 激活 调试 模式 ， 请 停止 应 用 程序 ， 然 后 设置 以 下 环境 变量 : 


(venv) $ export FLASK_DEBUG=1 


如 果 你 使 用 Microsoft Windows， 记 得 将 export 替换 成 set ° 


设置 环境 变量 FLASK_DEBUG 后 ， 重 启 服务 。 相 比 之 前 ， 终 端 上 的 输出 信息 会 有 所 变化 : 


Geny) microblog2 $ flask run 

* Serving Flask app "microblog" 

Forcing debug mode on 

Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 
Restarting with stat 

Debugger is active! 

Debugger PIN: 177-562-960 


ae TE, et E, 2 


现在 让 应 用 再 次 崩溃 ， 以 在 浏览 器 中 查看 交互 式 调试 器 : 


| sqlalchemy.exc.|ntegrityErrc 
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sqlalchemy.exc.IntegrityError 


sqlaichemy .exc. InNntegrityError: (sqlitej.IntegrityError) UNIQUE constraint failed: 
user.username (SQL: ‘UPDATE user SET username=?, about_me=? WHERE user.id = ?'] (parameters: 
(‘susan', “I'm the author of the Flask Mega-Tutorial you are now reading!", 2)] 


File “/Users/migu7781/Documents/dev/flask/microblog2/venv/lib/python3.6/site-packages/flask/app.py’, line 
1997, in call. 


return self.wsgi_app(environ, start_response) 
File "/Users/migu7781/Documents/dev/flask/microblog2/venv/lib/python3.6/site-packages/flask/app.py”, line 
1985, in wsgi_app 

response = self.handle_exception(e) 
File “/Users/migu7781/Documents/dev/flask/microblog2/venv/lib/python3.6/site-packages/flask/app.py’, line 
1540, in handle_exception 

reraise(exc_type, exc_value, tb) 
File “/Users/migu7781/Documents/dev/flask/microblog2/venv/lib/python3.6/site-packages/flask/_compat.py”, 
line 33, in reraise 

raise value 








File "/Users/migu7781/Documents/dev/flask/microblog2/venv/lib/python3.6/site-packages/flask/app.py”, line 
1982, in wsgi_app 


response = self.full_dispatch_request() 


该 调试 器 允许 你 展开 每 个 堆栈 框 来 查看 相应 的 源 代 码 上 下 文 。 你 也 可 以 在 任意 堆栈 框 上 打开 
Python 提示 符 并 执行 任何 有 效 的 Python 表达 式 ， 例 如 检查 变量 的 值 。 


永远 不 要 在 生产 服务 器 上 以 调试 模式 运行 Flask 应 用 ， 这 一 点 非常 重要 。 调试 器 允许 用 户 远程 
执行 服务 器 中 的 代码 ， 因 此 对 于 想 要 渗入 应 用 或 服务 器 的 和 恶意 用 户 来 说 ， 这 可 能 是 开门 拇 
Bo 作为 附加 的 安全 措施 ， 运 行 在 浏览 器 中 的 调试 器 开始 被 锁定 ， 并 且 在 第 一 次 使 用 时 会 要 
求 输入 一 个 PIN 码 〈 你 可 以 在 flask run 命令 的 输出 中 看 到 它 ) 。 


谈 到 调试 模式 的 话题 ， 我 不 得 不 提 到 的 第 二 个 重要 的 调试 模式 下 的 功能 ， 就 是 重 载 器 。 这 是 
一 个 非常 有 用 的 开发 功能 ， 可 以 在 源 文 件 被 修改 时 自动 重启 应 用 。 如 果 在 调试 模式 下 运 
行 flask run ， 则 可 以 在 开发 应 用 时 ， 每 当 保存 文件 ， 应 用 都 会 重新 启动 以 加 载 新 的 代码 。 


Pe 用 提供 了 一 个 机 制 来 自 定义 错误 页 面 ， ee 简单 而 枯燥 的 默认 页 
。 作为 例子 ， 让 我 们 为 HTTP 的 404 错 误 和 500 错 误 (两 个 最 常见 的 错误 页 面 ) 设置 自 定义 
De 。 为 其 他 错误 设置 页 面 的 方式 与 之 相同 。 


使 用 @errorhandler 装饰 器 来 声明 一 个 自 定 义 的 错误 处 理 器 。 我 将 把 我 的 错误 处 理 程 序 放 在 
一 个 新 的 app/errors.py 模 块 中 。 


from flask import render_template 
from app import app, db 


@app.errorhandler (404) 
def not_found_error(error): 
return render_template('404.htm1'), 404 


@app.errorhandler (500) 

def internal_error(error): 
db.session.rollback() 
return render_template('500.htm1'), 500 


ik 函数 与 视图 函数 非常 类 似 。 ， 我 将 返回 各 自 模板 的 内 容 。 
函数 在 模板 之 后 返回 第 二 个 值 ， 这 是 错误 代码 编号 。 对 于 之 前 我 创建 的 所 有 视图 遂 ens 
需要 添加 第 二 个 返回 值 ， eee on: (成 功 响应 的 状态 码 ) oo ， 这些 是 
错误 页 面 ， 所 以 我 希望 响应 的 状态 码 能 够 反映 出 来 。 


500 错 误 的 错误 处 理 程序 应 当 在 引发 数据 库 错 误 后 调用 ， 而 上 面 的 用 户 名 重复 实际 上 就 是 这 种 
情况 。 为 了 确保 任何 失败 的 数据 库 会 话 不 会 干扰 模板 触发 的 其 他 数据 库 访问 ， 我 执行 会 话 回 
滚 来 将 会 话 重 置 为 干净 的 状态 。 


404 错 误 的 模板 如 下 : 


{% extends "base.html" %} 
{% block content %} 
<hi>File Not Found</hi> 


<p><a href="{{ url_for('index') }}">Back</a></p> 
{% endblock %} 


500 错 误 的 模板 如 下 : 


{% extends "base.html" %} 
{% block content %} 
<hi>An unexpected error has occurred</h1> 
<p>The administrator has been notified. Sorry for the inconvenience! </p> 


<p><a href="{{ url_for('index') }}">Back</a></p> 
{% endblock %} 


这 两 个 模板 都 从 base. html 基础 模板 继承 而 来 ， 所 以 错误 页 面 与 应 用 的 普通 页 面 有 相同 的 外 
观 布局 。 


为 了 让 这 些 错误 处 理 程序 在 Flask 中 注册 ， 我 需要 在 应 用 实例 创建 后 导入 新 的 app/errors.py 模 
块 : 


# ... 


from app import routes，models，errors 


如 果 在 终端 界面 设置 环境 变量 FLASK_DEBUG=9 ， 然 后 再 次 出 发 重复 用 户 名 的 BUG， 你 将 会 看 到 
一 个 更 加 友好 的 错误 页 面 


Welcome to Microblog 


€ C û O localhost:50 





Microblog: Home Profile Logout 








An unexpected error has 
occurred 


The administrator has been notified. Sorry for the 
inconvenience! 


Back 


过 电子 邮件 发 送 错误 


Flask 提 供 的 默认 错误 处 理 机 制 的 另 一 个 问题 是 没有 通知 机 制 ， 错 误 的 堆栈 跟踪 只 是 被 打印 到 
终端 ， 这 意味 着 需要 监视 服务 器 进程 的 输出 才能 发 现 错误 。 在 开发 时 ， 这 是 非常 好 的 ， 但 是 
一 旦 将 应 用 部 署 在 生产 服务 器 上 ， 没 有 人 会 关心 输出 ， 因 此 需要 采用 更 强大 的 解决 方案 。 


我 认为 对 错误 发 现 采 取 积 极 主动 的 态度 是 非常 重要 的 。 如 果 生 产 环境 的 应 用 发 生 错误 ， 我 想 
立刻 知道 。 所 以 我 的 第 一 个 解决 方案 是 配置 Flask 在 发 生 错 误 之 后 立即 向 我 发 送 一 封 电子 邮 
件 ， 邮 件 正 文中 包含 错误 堆栈 跟踪 的 正文 。 


第 一 步 ， 添 加 邮件 服务 器 的 信息 到 配置 文件 中 : 


class Config(object): 
# i... 
MAIL_SERVER = os.environ.get('MAIL_SERVER' ) 
MAIL_PORT = int(os.environ.get('MAIL_PORT') or 25) 
MAIL_USE_TLS = os.environ.get('MAIL_USE_TLS') is not None 
MAIL_USERNAME = os.environ.get('MAIL_USERNAME ' ) 
MAIL_PASSWORD = os.environ.get('MAIL_PASSWORD' ) 
ADMINS = ['your-email@example.com' ] 


电子 邮件 的 配置 变量 包括 服务 器 和 端口 ， 启 用 加 密 S 
码 。 这 五 个 配置 变量 来 源 于 环境 变量 。 如果 电子 邮件 服务 器 没有 在 环境 中 设置 ， 那 么 我 将 禁 
用 电子 邮件 功能 。 电子 邮件 服务 器 端口 也 可 以 在 环境 变量 中 给 出 ， 但 是 如 果 和 
用 标准 端口 25。 电子 邮件 服务 器 凭证 默认 不 使 用 ， 但 可 以 根据 需要 提供 。 amns 配置 变量 
是 将 收 到 错误 报告 的 电子 邮件 地 址 列表 ， 所 以 你 自己 的 电子 邮件 地 址 应 该 在 该 列表 中 。 


Flask 使 用 Python 的 logging 包 来 写 它 的 日 志 ， 而 且 这 个 包 已 经 能 够 通过 电子 邮件 发 送 日 志 
了 。 我 所 需要 做 的 就 是 为 Flask 的 日 志 对 象 app.logger 添加 一 个 SMTPHandler 的 实例 : 


import logging 
from logging.handlers import SMTPHandler 


# ... 


if not app.debug: 
if app.config['MAIL_SERVER']: 

auth = None 

if app.config['MAIL_USERNAME'] or app.config['MAIL_PASSWORD']: 
auth = (app.config[ 'MAIL_USERNAME'], app.config[ 'MAIL_PASSWORD' ] ) 

secure = None 

if app.config['MAIL_USE_TLS']: 
secure = () 

mail_handler = SMTPHandler( 
mailhost=(app.config['MAIL_SERVER'], app.config['MAIL_PORT']), 
fromaddr='no-reply@' + app.config['MAIL_SERVER'], 
toaddrs=app.config['ADMINS'], subject='Microblog Failure', 
credentials=auth, secure=secure) 

mail_handler .setLevel(logging.ERROR) 

app. logger .addHandler (mail_handler ) 


如 你 所 见 ， 仅 当 应 用 未 以 调试 模式 运行 ， 且 配置 中 存在 邮件 服务 器 时 ， 我 才 会 启用 电子 邮件 
日 志 记 录 器 


设置 电子 邮件 日 志 记 录 器 的 步骤 因为 处 理 安全 可 选项 而 稍 显 繁 开 。 本 质 上 ， 上 面 的 代码 创建 
了 一 个 smTPHandler 实例 ， 设 置 它 的 级 别 ， 以 便 它 只 报告 错误 及 更 严重 级 别 的 信息 ， 而 不 是 警 
告 ， 常 规 信 息 或 调试 消息 ， 最 后 将 它 附 加 到 Flask 的 app.logger 对 象 中 。 


=a 


S 
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有 两 种 方法 来 测试 此 功能 。 最 简单 的 就 是 使 用 Python 的 SMTP 调 试 服务 
ie a 
端 会 话 并 在 其 上 运行 以 下 命 


。 这 是 一 个 模拟 的 
5 ， 请 打开 第 二 个 终 


a 


(venv) $ python -m smtpd -n -c DebuggingServer localhost:8025 


要 用 这 个 模拟 邮件 服务 器 来 测试 应 用 ， 那 么 你 将 设 


置 MAIL_SERVER=localhost 和 MAIL_PORT=8025 ° 


EAE: 本 段 中 去 处 了 说 明 设置 该 端口 需要 管理 员 权 限 的 部 分 ， 因 为 这 和 实际 情况 不 
符 。 原 文 如 下 : To test the ge with this server, then you will set 
MAIL_SERVER=localhost and MAIL _ PORT=8025 . If you are on a Linux or Mac OS system, 
you will likely need to prefix the command with sudo , so that it can execute with 
administration privileges. If you are on a Windows system, you may need to open your 
terminal window as an administrator. Administrator rights are needed for this command 
because ports below 1024 are administrator-only ports. Alternatively, you can change 
the port to a higher port number, say 5025, and set MAIL_PORT variable to your chosen 
port in the environment, and that will not require administration rights. 


保持 调试 SMTP 服 务 器 运行 并 返回 到 第 一 个 终端 ， 在 环境 中 设 

置 export MAIL_SERVER=localhost 和 MAIL_PORT=8025 (如 果 使 用 的 是 Microsoft Windows， 则 
使 用 Set 而 不 是 export) ° EL AOR. DEBUG 变 量 设置 为 0 或 者 根本 不 设置 ， 因 为 应 用 不 会 
在 调试 模式 中 发 送 电子 邮件 。 运行 该 应 用 并 再 次 触发 SQLAIchemy 错 误 ， 以 查看 运行 模拟 电 
子 邮件 服务 器 的 终端 会 话 如 何 显示 具有 完整 堆栈 跟踪 错误 的 电子 邮件 。 


这 个 功能 的 第 二 个 测试 方法 是 配置 一 个 昊 正 的 电子 邮件 服务 器 。 以 下 是 使 用 你 的 Gmail 帐户 的 
电子 邮件 服务 器 的 配置 


export MAIL_SERVER=smtp.googlemail.com 
export MAIL_PORT=587 

export MAIL_USE_TLS=1 

export MAIL_USERNAME=<your -gmail-username> 
export MAIL_PASSWORD=<your -gmail-password> 


如 果 你 使 用 的 是 Microsoft Windows， 记 住 在 每 一 条 语句 中 用 set 替换 掉 export ° 


Gmail 帐 户 中 的 安全 功能 可 能 会 阻止 应 用 通过 它 发 送 电 子 邮 件 ， 除 非 你 明确 允许 "安全 性 较 低 
的 应 用 程序 ”访问 你 的 Gmail 帐 户 。 可 以 阅读 此 处 来 了 解 具 体 情况 ， 如 果 你 担心 帐户 的 安全 
性 ， 可 以 创建 一 个 辅助 邮箱 帐户 ， 配 置 它 来 仅 用 于 测试 电子 邮件 功能 ， 或 者 你 可 以 暂时 启用 
允许 不 太 安 全 的 应 用 程序 来 运行 此 测试 ， 完 成 后 恢复 为 默认 值 。 


记录 日 志 到 文件 中 


通过 电子 邮件 来 接收 错误 提示 非常 棒 ， 但 在 其 他 场景 下 ， 有 时 候 就 有 些 不 足 了 。 有 些 错误 条 
件 既 不 是 一 个 Python 异常 又 不 是 重大 事故 ， 但 是 他 们 在 调试 的 时 候 也 是 有 足够 用 处 的 。 为 
此 ， 我 将 会 为 本 应 用 维持 一 个 日 志文 件 。 


为 了 启用 另 一 个 基于 文件 类 型 型 RotatingFileHandler 的 日 志 记 录 器 ， 需 要 以 和 电子 邮件 日 志 记 录 
器 类 似 的 方式 将 其 附加 到 应 用 的 logger 对 象 中 。 


# on. 
from logging.handlers import RotatingFileHandler 
import os 


# ... 


if not app.debug: 
# 


if not os.path.exists('logs'): 

os.mkdir('logs') 
file_handler = RotatingFileHandler('logs/microblog.log', maxBytes=10240, 

backupCount=10 ) 

file_handler.setFormatter(logging.Formatter ( 

"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]')) 
file_handler.setLevel( logging. INFO) 
app. logger .addHandler (file_handler ) 


app.logger.setLevel( logging. INFO) 
app.logger.info('Microblog startup') 


日 志文 件 的 存储 路 径 位 于 顶级 目录 下 ， 相 对 路 径 为 logs/microblog.log ， 如 果 其 不 存在 ， 则 
会 创建 它 。 


RotatingFileHandler 类 非常 棒 ， 国 为 它 可 以 切割 和 清理 日 志文 件 ， 以 确保 日 志文 件 在 应 用 运行 
很 长 时 间 时 不 会 变 得 太 大 。 本 处 ， 我 将 日 志文 件 的 大 小 限制 为 10KB， 并 只 保留 最 后 的 十 个 日 
志文 件 作为 备份 。 


logging.Formatter 类 为 日 志 消 息 提供 自 定义 格式 。 由 于 这 些 消息 正在 写 入 到 一 个 文件 ， 我 希 
望 它 们 可 以 存储 尽 可 能 多 的 信息 。 所 以 我 使 用 的 格式 包括 时 间 惟 、 日 志 记 录 级 别 、 消 息 以 及 
日 志 来 源 的 源 代 码 文 件 和 行 号 。 


为 了 使 日 志 记 录 更 有 用 ， 我 还 将 应 用 和 文件 日 志 记 录 器 的 日 志 记 录 级 别 降低 到 INFO 级 别 。 
如 果 你 不 熟悉 日 志 记录 类 别 ， 则 按照 严重 程度 递增 的 顺序 来 认识 它们 就 行 了 ， 分 别 


是 DEBUG ` INFO ` WARNING ` ERROR 和 CRITICAL ° 


日 志文 件 的 人 ， 服务 器 每 次 启动 时 都 会 在 日 志 中 写 入 一 行 。 当 此 应 用 在 生产 
服务 器 上 运行 时 ， 这 些 日 志 数 据 将 告诉 你 服务 器 何 时 重新 启动 过 。 


修复 用 户 名 重复 的 BUG 
利用 用 户 名 重复 BUG 这 么 久 ， 现 在 时 候 向 你 展示 如 何 修复 它 了 。 


你 是 否 还 记得 ， RegistrationForm 已 经 实现 了 对 用 户 名 的 验证 ， 但 是 编辑 表单 的 要 求 稍 有 不 
eee 我 需要 确保 在 表单 中 输入 的 用 户 名 不 存在 于 数据 库 中 。 在 编辑 个 人 资料 表 
单 中 ， 我 必须 做 同样 的 检查 ， 但 有 一 个 例外 。 如 果 用 户 不 改变 原始 用 户 名 ， 那 么 验证 应 该 允 
许 ， 因 为 该 用 户 名 已 经 被 分 配给 该 用 户 。 下 面 你 可 以 看 到 我 为 这 个 表单 实现 了 用 户 名 验证 : 


class EditProfileForm(FlaskForm): 
username = StringField('Username', validators=[DataRequired()]) 
about_me = TextAreaField('About me', validators=[Length(min=0, max=140)]) 
submit = SubmitField('Submit' ) 


def _ init__(self, original_username, *args, **kwargs): 


super (EditProfileForm, self). init __(*args, **kwargs) 
self.original_username = original_username 


def validate_username(self, username): 
if username.data != self.original_username: 
user = User.query.filter_by(username=self.username.data).first() 
if user is not None: 
raise ValidationError('Please use a different username. ') 


该 实现 使 用 了 一 个 自 定义 的 验证 方法 ， 接 受 表 单 中 的 用 户 名 作为 参数 。 这 个 用 户 名 保存 为 一 
个 实例 变量 ， 并 在 validate_username() 方法 中 被 校 验 。 如 果 在 表单 中 输入 的 用 户 名 与 原始 用 
户 名 相同 ， 那 么 就 没有 必要 检查 数据 库 是 否 有 重复 了 。 


为 了 使 得 新 增 的 验证 方法 生效 ， 我 需要 在 对 应 视图 函数 中 添加 当前 用 户 名 到 表单 的 Username 
字段 中 : 


@app.route('/edit_profile', methods=['GET', 'POST']) 
@login_required 
def edit_profile(): 

form = EditProfileForm(current_user.username ) 

# on, 


现在 这 个 BUG 已 经 修复 了 ， 大 多 数 情况 下 ， 以 后 在 编辑 个 人 资料 时 出 现 用 户 名 重复 的 提交 将 
P E 。 但 这 不 是 一 个 完美 的 解决 方案 ， 因 为 当 两 个 或 更 多 进程 同时 访问 数据 库 时 ， 

可 能 不 起 作用 。 假 如 存在 验证 通过 的 进程 A 和 B 都 尝试 修改 用 户 名 为 同一 个 ， 但 稍 后 进程 A 
nee 名 时 ， 数 据 库 已 被 进程 B 更 改 ， 无 法 重 命名 为 该 用 户 名 ， 会 再 次 引发 数据 库 异 常 
除了 有 很 多 服务 器 进程 并 且 非 常 繁忙 的 应 用 之 外 ， 这 种 情况 是 不 太 可 能 的 ， 所 以 现在 我 不 会 
为 此 担心 。 


此 时 ， 你 可 以 尝试 再 次 重 现 该 错误 ， 以 了 解 新 的 表单 验证 方法 如 何 防止 该 错误 。 


A XË Á The Flask Mega-Tutorial Part VIII: Followers 


这 是 Flask Mega-Tutorial 系 列 的 第 八 部 分 ， 我 将 告诉 你 如 何 实现 类 似 于 Twitter 和 其 他 社交 网 络 
的 "粉丝" 功能。 


在 本 章 中 ， 我 将 更 多 地 使 用 应 用 的 数据 库 。 我 希望 应 用 的 用 户 能 够 轻松 便捷 地 关注 其 他 用 
户 。 所 以 我 要 扩展 数据 库 ， 以 便 跟 踪 谁 关注 了 谁 ， 这 上 比 你 想象 的 要 难得 多 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


深入 理解 数据 库 关系 


我 上 面 说 过 ， 我 想 为 每 个 用 户 维护 一 个 “粉丝 "用户 列表 和 "关注 "用 户 列 表 。 不 幸 的 是 ， 关 系 型 
数据 库 没 有 列表 类 型 的 字段 来 保存 它们 ， 那 么 只 能 通过 表 的 现 有 字段 和 他 们 之 间 的 关系 来 实 

现 。 

数据 库 已 有 一 个 代表 用 户 的 表 ， 所 以 剩 下 的 就 是 如 何 正确 地 组 织 他 们 之 间 的 关注 与 被 关注 的 

关系 。 这 正 是 回顾 基本 数据 库 关系 类 型 的 好 时 机 : 


一 对 多 


我 已 经 在 第 四 章 中 用 过 了 一 对 多 关系 。 这 是 该 关系 的 7 
和 post) 


“意图 ( 译 者 注 : 实际 表 名 分 别 为 User 


3 


_VARCHAR (120) 


password _| hash VARCHAR (128) 





用 户 和 用 户 动态 通过 这 个 关系 来 关联 。 其 中 ， 一 个 用 户 拥有 多 条 用 户 动态 ， 而 一 条 用 户 动态 
属于 一 个 用 户 (作者 ) 。 数 据 库 在 多 的 这 方 使 用 了 一 个 外 键 以 表示 一 对 多 关系 。 在 上 面 的 一 
对 多 关系 中 ， 外 键 是 post A userid 字段， 这 个 字段 将 用 户 的 每 条 动态 都 与 其 作者 关联 了 
起 来 。 


很 明显 ， userid 字段 提供 了 直接 访问 给 定 用 户 动态 的 作者 ， 但 是 反 向 呢 ? 透 过 这 ann ， 
我 如 何 通 过 给 定 的 用 户 来 获得 其 用 户 动态 的 列表 ? post RPA userid 字段 也 足以 回答 
问题 ， 数 据 库 具有 索引 ， 可 以 进行 高 效 的 查询 “返回 所 有 User id 字段 等 于 X 的 用 户 动态 ”。 


多 对 多 关系 会 更 加 复杂 ， 举 个 例子 ， 数 据 库 中 有 students 表 和 teachers 表 ， 一 名 学 生 学 习 
多 位 老师 的 课程 ， 一 位 老师 教授 多 名 学 生 。 这 就 像 两 个 重 登 的 一 对 多 关系 。 


对 于 这 种 类 型 的 关系 ， 我 想 要 能 够 查询 数据 库 来 获取 教授 给 定 学 生 的 教师 的 列表 ， 以 及 某 个 
教师 课程 中 的 学 生 的 列表 。 想 要 在 关系 型 数据 库 中 梳理 这 样 的 关系 并 非 轻易 而 举 ， 因 为 无 法 
通过 向 现 有 表 添 加 外 键 来 完成 此 操作 。 


展现 多 对 多 关系 需要 使 用 额外 的 关联 表 。 以 下 是 数据 库 如 何 查找 学 生 和 教师 的 示例 : 


students | teachers 





虽然 起 初 看 起 来 并 不 明显 ， 但 具有 两 个 外 键 的 关联 表 的 确 能 够 有 效 地 回答 所 有 多 对 多 关系 的 


查询 。 


多 对 一 和 一 对 一 

多 对 一 关系 类 似 于 一 对 多 关系 。 不 同 的 是 ， 这 种 关系 是 从 “多 ”的 角度 来 看 的 。 

一 对 一 的 关系 是 一 对 多 的 特例 。 实现 是 相似 的 ， 但 是 一 个 约束 被 添加 到 数据 库 ， 以 防 

止 “ 多 ”一 方 有 多 个 链接 。 虽 然 有 这 种 类 型 的 关系 是 有 用 的 ， 但 并 不 像 其 他 类 型 那么 普遍 。 
译 者 注 : 如 果 读 者 有 兴趣 ， 也 可 以 看 看 我 写 的 一 篇 类 似 的 数据 库 关 系 文 章 一 “Web 开发 
中 常用 的 数据 关系 


实现 粉丝 机 制 

查看 所 有 关系 类 型 的 概要 ， 很 容易 确定 维护 粉丝 关系 的 正确 数据 模型 是 多 对 多 关系 ， 因 为 用 
户 可 以 关注 多 个 其 他 用 户 ， 并 且 用 户 可 以 拥有 多 个 粉丝 。 不过， 在 学 生 和 老师 的 例子 中 ， 多 
对 多 关系 关联 了 两 个 实体 。 但 在 粉丝 关系 中 ， 用 户 关注 其 他 用 户 ， 只 有 一 个 用 户 实 体 。 那 

么 ， 多 对 多 关系 的 第 二 个 实体 是 什么 呢 ? 

该 关系 的 第 二 个 实体 也 是 用 户 。 一 个 类 的 实例 被 关联 到 同一 个 类 的 其 他 实例 的 关系 被 称 为 自 
引用 关系 ， 这 正 是 我 在 这 里 所 用 到 的 。 


使 用 自 引 用 多 对 多 关系 来 实现 粉丝 机 制 的 表 结构 示意 图 : 














followers 
follower_id INTEGER 


followed_id INTEGER | 


username VARCHAR (64) | 







email VARCHAR (120) 


password_hash VARCHAR (128) 


followers 表 是 关系 的 关联 表 。 此 表 中 的 外 键 都 指向 用 户 表 中 的 数据 行 ， 因 为 它 将 用 户 关 联 
到 用 户 。 该 表 中 的 每 个 记录 代表 关注 者 和 被 关注 者 的 一 个 关系 。 像 学 生 和 老师 的 例子 一 样 ， 
像 这 样 的 设计 允许 数据 库 回 答 所 有 关于 关注 和 被 关注 的 问题 ， 并 且 足 够 干净 利落 。 


数据 库 模 型 的 实现 
首先 ， 让 我 们 在 数据 库 中 添加 粉丝 机 制 吧 。 这 是 Followers 关联 表 : 


followers = db.Table('followers', 
db.Column('follower_id', db.Integer, db.Foreignkey('user.id')), 
db.Column('followed_id', db.Integer, db.ForeignKkey('user.id')) 


这 是 上 图 中 关联 表 的 直接 翻译 。 请 注意 ， 我 没有 像 我 为 用 户 和 用 户 动态 所 做 的 那样 ， 将 表 声 
明 为 模型 。 因 为 这 是 一 个 除了 外 键 没 有 其 他 数据 的 辅助 表 ， 所 以 我 创建 它 的 时 候 没 有 关联 到 


现在 我 可 以 在 用 户 表 中 声明 多 对 多 的 关系 了 : 


class User(UserMixin, db.Model): 
# ... 
followed = db.relationship( 
"User', secondary=followers, 
primaryjoin=(followers.c.follower_id == id), 
secondaryjoin=(followers.c.followed_id == id), 
backref=db.backref('followers', lazy='dynamic'), lazy='dynamic' ) 


建立 关系 的 过 程 实 属 不 昂 。 就 像 我 为 post 一 对 多 关系 所 做 的 那样 ， 我 使 

用 db.relationship 函数 来 定义 模型 类 中 的 关系 。 这 种 关系 将 User 实例 关联 到 其 他 user 实 
例 ， 所 以 按照 惯例 ， 对 于 通过 这 种 关系 关联 的 一 对 用 户 来 说 ， 左 侧 用 户 关注 右 侧 用 户 。 我 在 
左 侧 的 用 户 中 定义 了 followed 的 关系 ， 因 为 当 我 从 左 侧 查 询 这 个 关系 时 ， 我 将 得 到 已 关注 的 
APIK (PEMIKIR) 。 让 我 们 和 逐个 检查 这 个 db,relationship() 所 有 的 参数 : 


o 'User' 是 关系 当中 的 右 侧 实体 〈 将 堪 侧 实 体 看 成 是 上 级 类 ) 。 由 于 这 是 自 引用 关系 ， 所 
以 我 不 得 不 在 两 侧 都 使 用 同一 个 实体 。 

@ secondary 指定 了 用 于 该 关系 的 关联 表 ， 就 是 使 用 我 在 上 面 定 义 的 followers ° 

© primaryjoin 指明 了 通过 关系 表 关 联 到 左 侧 实 体 (关注 者 ) WAH 。 关 系 中 的 左 侧 的 
join 条 件 是 关系 表 中 的 follower_id 字段 与 这 个 关注 者 的 用 户 |D 匹 


AG ° followers.c.follower_id 表达 式 引 用 了 该 关系 表 中 的 follower_id 列 。 
esecondaryjoin 指明 了 通过 关系 表 关 联 到 右 侧 实体 (被 关注 者 ) 的 条 件 。 这 个 条 件 
与 primaryjoin 类 似 ， 唯 一 的 区 别 在 于 ， 现 在 我 使 用 关系 表 的 字段 的 是 followed id T ° 
© backref 定义 了 右 侧 实体 如 何 访 问 该 关系 。 在 左 侧 ， 关 系 被 命名 为 followed ， 所 以 在 右 
侧 我 将 使 用 followers 来 表示 所 有 左 侧 用 户 的 列表 ， 即 粉丝 列表 。 附 加 的 lazy 参数 表示 
这 个 查询 的 执行 模式 ， 设 置 为 动态 模式 的 查询 不 会 立即 执行 ， 直 到 被 调用 ， 这 也 是 我 设 
置 用 户 动态 一 对 多 的 关系 的 方式 。 
e lazy 和 backref 中 的 lazy 类 似 ， 只 不 过 当前 的 这 个 是 应 用 于 左 侧 实体 ， backref 中 的 
是 应 用 于 右 侧 实体 。 


如 果 理 解 起 来 比较 困难 ， 你 也 不 必 过 于 担心 。 我 待 会 儿 就 会 向 你 展示 如 何 利 用 这 些 关系 来 执 
行 查询 ， 一 切 就 会 变 得 清晰 明了 。 


数据 库 的 变更 ， 需 要 记录 到 一 个 新 的 数据 库 迁 移 中 : 


(venv) $ flask db migrate -m "followers" 
INFO [alembic.runtime.migration] Context impl SQLiteImpl. 
INFO [alembic.runtime.migration] Will assume non-transactional DDL. 
INFO [alembic.autogenerate.compare] Detected added table 'followers' 
Generating /home/miguel/microblog/migrations/versions/ae346256b650_followers.py ... 
done 


(venv) $ flask db upgrade 
INFO [alembic.runtime.migration] Context impl SQLiteImpl. 
INFO [alembic.runtime.migration] Will assume non-transactional DDL. 


INFO [alembic.runtime.migration] Running upgrade 37f06a334dbf -> ae346256b650, follow 
ers 


关注 和 取消 关注 


感谢 SQLAIchemy ORM ， 一 个 用 户 关注 另 一 个 用 户 的 行为 可 以 通过 Followed 关系 抽象 成 一 个 
列表 来 简便 使 用 。 例 如 ， 如 果 我 有 两 个 用 户 存 储 在 user1 和 user2 变量 中 ， 我 可 以 用 下 面 这 
个 简单 的 语句 来 实现 


user1.followed.append(user2) 


要 取消 关注 该 用 户 ， 我 可 以 这 么 做 : 

user1.followed.remove(user2) 
即便 关注 和 取消 关注 的 操作 相当 容易 ， 我 仍然 想 提 高 这 段 代码 的 可 重用 性 ， 所 以 我 不 会 直接 
在 代码 中 使 用 “appends” 和 “removes”， 取 而 代 之 ， 我 将 在 user 模型 中 实 


现 “follow”" 和 “unfollow” 方 法 。 最 好 将 应 用 公 辑 从 视图 函数 转移 到 模型 或 其 他 辅助 类 或 辅助 模块 
中 ， 因 为 你 会 在 本 章 之 后 将 会 看 到 ， 这 使 得 单元 测试 更 加 容易 。 


下 面 是 用 户 模型 中 添加 和 删除 关注 关系 的 代码 变更 : 


class User(UserMixin, db.Model): 
#... 


def follow(self, user): 
if not self.is_following(user): 
self.followed.append(user ) 


def unfollow(self, user): 
if self.is_following(user): 
self. followed. remove(user ) 


def is_following(self, user): 
return self. followed. filter ( 
followers.c.followed_id == user.id).count() > 0 


follow() 和 unfollow() 方法 使 用 关系 对 象 的 append() 和 remove() 方法 。 有 必要 在 处 理 关 系 
之 前 ， 使 用 一 个 is_following() 方法 来 确认 操作 的 前 提 条 件 是 否 符合 ， 例 如 ， 如 果 我 要 

R usera 关注 user2 ， 但 事实 证 明 这 个 关系 在 数据 库 中 已 经 存在 ， 我 就 没 必 要 重复 操作 了 。 
相同 的 逻辑 可 以 应 用 于 取消 关注 。 


is_following() 方法 发 出 一 个 关于 followed 关系 的 查询 来 检查 两 个 用 户 之 间 的 关系 是 否 已 经 
存在 。 你 已 经 看 到 过 我 使 用 SQLAIchemy 查 询 对 象 的 filter_by() 方法 ， 例 如 ， 查 找 给 定 用 
户 名 的 用 户 。 我 在 这 里 使 用 的 filter() 方法 很 类 似 ， 但 是 更 加 偏向 底层 ， 因 为 它 可 以 包含 任 
意 的 过 滤 条 件 ， 而 不 像 filter_by() ? 它 只 能 检查 是 否 等 于 一 个 常量 值 。 我 

在 is_following() 中 使 用 的 过 滤 条 件 是 ， 查 找 关联 表 中 左 侧 外 键 设 置 为 self 用 户 且 右 侧 设置 
为 user 参数 的 数据 行 。 查 询 以 count() 方法 结束 ， 返 回 结 果 的 数量 。 这 个 查询 的 结果 

是 8 或 1， 因 此 检查 计数 是 1 还 是 大 于 0 实际 上 是 相等 的 。 至 于 其 他 的 查询 结 

符 all() 和 first() ， 你 已 经 看 到 我 使 用 过 了 。 


查看 已 关注 用 户 的 动态 


在 数据 库 中 支持 粉丝 机 制 的 工作 几 近 尾声 ， 但 是 我 却 遗漏 了 一 项 重要 的 功能 。 应 用 主页 中 需 
要 展示 已 登录 用 户 关 注 的 其 他 所 有 用 户 的 动态 ， 我 需要 用 数据 库 查询 来 返回 这 些 用 户 动态 。 


最 显而易见 的 方案 是 先 执 行 一 个 查询 以 返回 已 关注 用 户 的 列表 ， 如 你 所 知 ， 可 以 使 
用 user.followed.all() 语句 。 然 后 对 每 个 已 关注 的 用 户 执 行 一 个 查询 来 返回 他 们 的 用 户 动 
态 。 最 后 将 所 有 用 户 的 动态 按照 日 期 时 间 倒 序 合 并 到 一 个 列表 中 。 听 起 来 不 错 ? 其 实 不 然 。 


这 种 方法 有 几 个 问题 。 如 果 一 个 用 户 关注 了 一 千 人 ， 会 发 生 什 么 ? 我 需要 执行 一 千 个 数据 库 
查询 来 收集 所 有 的 用 户 动态 。 然后 我 需要 合并 和 排序 内 存 中 的 一 千 个 列表 。 作为 第 二 个 问 
题 ， 考 虑 到 应 用 主页 最 终 将 实现 分 页 ， 所 以 它 不 会 显示 所 有 可 用 的 用 户 动 态 ， 只 能 是 前 几 
个 ， 并 显示 一 个 链接 来 提供 感 兴 趣 的 用 户 查 看 更 多 动态 。 如果 我 要 按 它们 的 日 期 排序 来 显示 
动态 ， 我 怎么 能 知道 哪些 用 户 动态 才 是 所 有 用 户 中 最 新 的 呢 ? 除非 我 首先 得 到 了 所 有 的 用 户 
动态 并 对 其 进行 排序 。 这 实际 上 是 一 个 粮 糕 的 解决 方案 ， 不 能 很 好 地 应 对 规模 化 。 


用 户 动 态 的 合并 和 排序 操作 是 无 法 避免 的 ， 但 是 在 应 用 中 执行 会 导致 效率 十 分 低下 ， 而 这 种 
工作 是 关系 数据 库 擅 长 的 。 我 可 以 使 用 数据 库 的 索引 ， 命 令 它 以 更 有 效 的 方式 执行 查询 和 排 
Fro 所 以 我 凌 正 想 要 提供 的 方案 是 ， 定 义 我 想 要 得 到 的 信息 来 执行 一 个 数据 库 查 询 ， 然 后 让 
数据 库 找 出 如 何以 最 有 效 的 方式 来 提取 这 些 信 息 。 


看 看 下 面 的 这 个 查询 : 


class User(db.Model): 
H... 
def followed_posts(self): 
return Post.query.join( 
followers, (followers.c.followed_id == Post.user_id)).filter( 
followers.c.follower_id == self.id).order_by( 
Post.timestamp.desc()) 


这 是 迄今 为 止 我 在 这 个 应 用 中 使 用 的 最 复杂 的 查询 。 我 将 尝试 一 步 一 步 地 解读 这 个 查询 。 如 
果 你 看 一 下 这 个 查询 的 结构 ， 你 会 注意 到 有 三 个 主要 部 分 ， 分 别 
是 join() ` filter() 和 order_by() ， 他 们 都 是 SQLAIchemy 查 询 对 象 的 方法 : 


Post.query.join(...).filter(...).order_by(...) 


联合 查询 


要 理解 join 操作 的 功能 ， 我 们 来 看 一 个 例子 。 假 设 我 有 一 个 包含 以 下 内 容 的 User 表 : 


id username 
1 john 
2 Susan 
3 mary 
4 david 


为 了 简单 起 见 ， 我 只 会 保留 用 户 模 型 的 id 和 username 字段 以 便 进 行 查询 ， 其 他 的 都 略 去 。 


假设 followers 关系 表 中 数据 表达 的 是 用 户 john 关注 用 户 susan 和 david ， 用 户 susan 关 
注 用 户 mary ， 用 户 mary 关注 用 户 david 。 这 些 的 数据 如 下 表 所 示 : 


follower_id followed_id 
1 2 
1 4 
2 3 
3 4 
最 后 ， 用 户 动态 表 中 包含 了 每 个 用 户 的 一 条 动态 : 


id text user_id 


1 post from susan 2 
2 post from mary 3 
3 post from david 4 
4 post from john 1 
这 张 表 也 省 略 了 一 些 不 属于 这 个 讨论 范围 的 字段 。 
这 是 我 为 该 查询 再 次 设计 的 join() 调用 : 
Post.query.join(followers, (followers.c.followed_id == Post.user_id)) 


我 在 用 户 动态 表 上 调用 join 操作 。 第 一 个 参数 是 followers 关 联 表 ， 第 二 个 参数 是 join 条 件 。 我 
的 这 个 调用 表达 的 含义 是 我 希望 数据 库 创建 一 个 临时 表 ， 它 将 用 户 动 态 表 和 关注 者 表 中 的 数 
据 结合 在 一 起 。 数据 将 根据 参数 传递 的 条 件 进行 合并 。 


我 使 用 的 条 件 表示 了 followers 关 系 表 的 followed id 字段 必须 等 于 用 户 动 态 表 的 userid F 
段 。 要 执行 此 合并 ， 数 据 库 将 从 用 户 动态 表 (join 的 堪 侧 ) 获取 每 条 记录 ， 并 追 

加 followers KAR (join 49 Æ 4] ) 中 的 匹配 条 件 的 所 有 记录 。 如 果 followers 关系 表 中 有 多 
个 记录 符合 条 件 ， 那 么 用 户 动态 数据 行将 重复 出 现 。 如 果 对 于 一 个 给 定 的 用 户 动 态 ， 
followers 关 系 表 中 却 没 有 匹配 ， 那 么 该 用 户 动态 的 记录 不 会 出 现在 join 操作 的 结果 中 。 


利用 我 上 面 定义 的 示例 数据 ， 执 行 join 操作 的 结果 如 下 : 


id text user_id follower_id followed_id 
1 post from susan 2 1 2 
2 post from mary 3 2 3 
3 post from david 4 1 4 
3 post from david 4 3 4 


注意 user_id 和 followed_id 列 在 所 有 数据 行 中 都 是 相等 的 ， 因 为 这 是 join 条 件 。 KAA 
È john 的 用 户 动态 不 会 出 现在 临时 表 中 ， 因 为 被 关注 列表 中 没有 包含 john AP > He 
说 ， 没 有 任何 人 关注 john。 MRA david 的 用 户 动态 出 现 了 两 次 ， 因 为 该 用 户 有 两 个 粉丝 。 


虽然 创建 了 这 个 join 操作 ， 但 却 没有 得 到 想 要 的 结果 。 请 继续 看 下 去 ， 因 为 这 只 是 更 大 的 查询 


的 一 部 分 。 


Join 操 作 给 了 我 一 个 所 有 被 关注 用 户 的 用 户 动态 的 列表 ， 远 超出 我 想 要 的 那 部 分 数据 。 我 只 
对 这 个 列表 的 一 个 子 集 感 兴 趣 一 一 某 个 用 户 关注 的 用 户 们 的 动态 ， 所 以 我 需要 用 filter() 来 
别 除 所 有 我 不 需要 的 数据 。 


这 是 过 滤 部 分 的 查询 语句 : 


filter(followers.c.follower_id == self.id) 


该 查询 是 user 类 的 一 个 方法 ， self.id 表达 式 是 指 我 感 兴趣 的 用 户 的 ID。 filter() 挑选 临 
时 表 中 follower_id 列 等 于 这 个 ID 的 行 ， 换 名 话说 ， 我 只 保留 follower( 粉 丝 ) 是 该 用 户 的 数 
据 。 


假如 我 现在 对 id 为 1 的 用 户 john 能 看 到 的 用 户 动态 感 兴趣 ， 这 是 从 临时 表 过 滤 后 的 结果 : 


id text user_id follower_id followed_id 
1 post from susan 2 1 2 
3 post from david 4 1 4 
这 正 是 我 想 要 的 结果 ! 


请 记 住 ， 查 询 是 从 Post 类 中 发 出 的 ， 所 以 尽管 我 曾经 得 到 了 由 数据 库 创 建 的 一 个 临时 表 来 作 

为 查询 的 一 部 分 ， 但 结果 将 是 包含 在 此 临时 表 中 的 用 户 动态 ， 而 不 会 存在 由 于 执行 join 操作 添 

加 的 其 他 列 。 

排序 

查询 流程 的 最 后 一 步 是 对 结果 进行 排序 。 这 部 分 的 查询 语句 如 下 : 
order_by(Post.timestamp.desc()) 


在 这 里 ， 我 要 说 的 是 ， 我 希望 使 用 用 户 动态 产生 的 时 间 戳 按 降序 排列 结果 列表 。 排 序 之 后 ， 
第 一 个 结果 将 是 最 新 的 用 户 动态 。 


组 合 自身 动态 和 关注 的 用 户 动态 


我 在 followed_posts() 函数 中 使 用 的 查询 是 非常 有 用 的 ， 但 有 一 个 限制 ， 人 们 期 望 看 到 他 们 
自己 的 动态 包含 在 他 们 的 关注 的 用 户 动态 的 时 间 线 中 ， 而 该 查询 却 力 有 未 还 。 


有 两 种 可 能 的 方式 来 扩展 此 查询 以 包含 用 户 自己 的 动态 。 最 直截了当 的 方法 是 将 查询 保持 原 
样 ， 但 要 确保 所 有 用 户 都 关注 了 他 们 自己 。 如 果 你 是 你 自己 的 粉丝 ， 那 么 上 面 的 查询 就 会 找 
到 你 自己 的 动态 以 及 你 关注 的 所 有 人 的 动态 。 这 种 方法 的 缺点 是 会 影响 粉丝 的 统计 数据 。 所 


有 人 的 粉丝 数量 都 将 加 一 ， 所 以 它们 必须 在 显示 之 前 进行 调整 。 第 二 种 方法 是 通过 创建 第 二 
个 查询 返回 用 户 自己 的 动态 ， 然 后 使 用 “Union” 操 作 将 两 个 查询 合并 为 一 个 查询 。 


深思 熟 虑 之 后 ， 我 选择 了 第 二 个 方案 。 下 面 你 可 以 看 到 followed_posts() 函数 已 被 扩展 成 通 
过 联合 查 ee 自己 的 动态 : 


def followed_posts(self): 
followed = Post.query.join( 
followers, (followers.c.followed_id == Post.user_id)).filter( 
followers.c.follower_id == self.id) 
own = Post.query.filter_by(user_id=self.id) 
return followed.union(own).order_by(Post.timestamp.desc() ) 


请 注意 ， followed 和 own 查询 结果 集 是 在 排序 之 前 进行 的 合并 。 


对 用 户 模 型 执行 单元 测试 


虽然 我 不 担心 这 个 稍 显 " 复 杂 ” 的 粉丝 机 制 的 运行 是 否 无 误 。 但 当 我 编写 举足轻重 的 代码 时 ， 
我 担心 的 是 我 在 应 用 的 不 同 部 分 修改 了 代码 之 后 ， = 工作 。 确保 
已 经 编写 的 代码 在 将 来 继续 有 效 的 最 佳 方法 是 创建 一 套 自 动 化 测试 ， 你 可 以 在 每 次 更 新 代码 
后 执行 测试 。 


Python 包含 一 个 非常 有 用 的 unittest ， 可 以 轻松 编写 和 执行 单元 测试 。 让 我 们 来 
A user 类 中 的 现 有 方法 编 ee tests.py 模 块 : 


from datetime import datetime, timedelta 
import unittest 

from app import app, db 

from app.models import User, Post 


class UserModelCase(unittest.TestCase): 
def setUp(self): 
app.config[ 'SQLALCHEMY_DATABASE_URI'] = 'sqlite://' 
db.create_all() 


def tearDown(self): 
db.session.remove( ) 
db.drop_all() 


def test_password_hashing(self): 
u = User(username='susan' ) 
u.set_password('cat') 
self .assertFalse(u.check_password('dog' )) 
self .assertTrue(u.check_password('cat')) 


def test_avatar(self): 
u = User(username='john', email='john@example.com' ) 
self .assertEqual(u.avatar(128), ('https://www.gravatar.com/avatar/' 
"d4c74594d841139328695756648b6bd6 ' 
'?d=identicon&s=128' ) ) 


def test_follow(self): 
u1 = User(username='john', email='john@example.com' ) 
u2 = User(username='susan', email='susan@example.com' ) 
db.session.add(u1) 
db.session.add(u2) 
db.session.commit() 


self .assertEqual(u1.followed.all(), 
self .assertEqual(u1.followers.all(), 


ui. follow(u2) 
db.session.commit() 
-assertTrue(u1.is_fol 


self 
self 
self 
self 
self 


-assertEqual(u1. 
-assertEqual(u1. 
-assertEqual(u2. 
-assertEqual(u2. 


follo 
follo 
follo 
follo 


u1.unfollow(u2) 
db.session.commit() 


self .assertFalse(u1. 
self .assertEqual(u1. 
self .assertEqual(u2. 


def 


is_fo 
follo 
follo 


test_follow_posts(self): 


# create four users 


[]) 
[]) 


lowing(u2)) 
wed.count(), 1) 
wed.first().username, 
wers.count(), 1) 
wers.first().username, 


llowing(u2)) 
wed.count(), 0) 
wers.count(), 0) 


"susan' ) 


"john' ) 


u1 = User(username='john', email='john@example.com' ) 

u2 = User(username='susan', email='susan@example.com' ) 

u3 = User(username='mary', email='mary@example.com' ) 

u4 = User(username='david', email='david@example.com' ) 

db.session.add_all([u1, u2, u3, u4]) 

# create four posts 

now = datetime.utcnow( ) 

p1 = Post(body="post from john", author=u1, 
timestamp=now + timedelta(seconds=1) ) 

p2 = Post(body="post from susan", author=u2, 
timestamp=now + timedelta(seconds=4) ) 

p3 = Post(body="post from mary", author=u3, 
timestamp=now + timedelta(seconds=3) ) 

p4 = Post(body="post from david", author=u4, 
timestamp=now + timedelta(seconds=2) ) 

db.session.add_all([p1, p2, p3, p4]) 


db 


.session.commit() 


# setup the followers 


u1.follow(u2) # john fol 
u1.follow(u4) # john fol 
u2.follow(u3) # susan fo 
u3.follow(u4) # mary fol 
db.session.commit() 


lows susan 
lows david 
llows mary 
lows david 


# check the followed posts of each user 


f1 
f2 
f3 
f4 
self 
self 
self 
self 


if name 


-assertEqual(f1, 
.assertEqual(f2, 
.assertEqual(f3, 
-assertEqual(f4, 


u1.followed_posts() 
u2.followed_posts() 
u3.followed_posts() 
u4.followed_posts() 
[p2, 
[p2, 
[p3, 
[p4] 


main__': 





unittest .main(verbosity=2) 


我 添加 了 四 个 用 户 模型 的 测试 ， 
setUp() 和 tearDown() 方法 是 单元 测试 框架 分 别 在 每 个 测试 之 前 和 之 后 执行 的 特殊 方法 。 我 

在 setup() 中 实现 了 一 些小 技巧 ， 以 防止 单元 测试 使 用 我 用 于 开发 的 常规 数据 库 。 通过 将 应 

过 SQLAIchemy 来 使 用 SQLite 内 存 数据 库 。 

这 是 从 头 开 始 创 ， 在 测试 中 相当 

迁移 的 手段 向 你 展 


用 配置 更 改 为 sqlite:// 
db.create_all() 创建 所 有 的 数据 库 表 。 
而 对 于 开发 环境 和 生产 环境 的 数据 库 结 构 管 


好 用 。 
示 过 了 。 


> 我 在 测试 


包含 密码 哈 希 、 用 户头 


.all() 
.all() 
.all() 
.all() 


p4, p1]) 
p3]) 
aa 


过 程 中 通 


“ 像 和 粉丝 功能 。 


理 ， 我 已 经 通 


你 可 以 使 用 以 下 命令 运行 整个 测试 组 件 : 


从 现在 起 ， 每 次 对 应 用 进行 


(venv) $ python tests.py 


test_avatar (__main__.UserModelCase) ... ok 
test_follow (__main__.UserModelCase) ... ok 
test_follow_posts (__main__.UserModelCase) ... ok 
test_password_hashing (__main__.UserModelCase) ... ok 


Ran 4 tests in 0.494s 


OK 


影响 。 另外 ， 每 次 将 另 一 个 功能 添加 到 应 用 时 ， 都 应 该 为 其 


在 应 用 中 集成 粉丝 机 制 


数据 库 和 模型 中 粉丝 机 制 的 实现 现在 已 经 完成 ， 但 是 我 没有 将 


eer ea 


编写 一 个 单元 测试 。 


它 集成 到 应 用 中 ， 所 以 我 现在 


要 添加 这 个 功能 。 n 高 兴 的 是 ， 实 现 它 没有 什么 大 的 挑战 ， 都 将 基于 你 已 经 学 过 的 概念 。 
路 由 


让 我 们 来 添加 两 个 新 的 


I: 


@app. route('/follow/<username>' ) 
@login_required 
def follow(username): 


user = User.query.filter_by(username=username) .first() 
if user is None: 
flash('User {} not found.'.format(username) ) 
return redirect(url_for('index')) 
if user == current_user: 
flash('You cannot follow yourself!') 
return redirect(url_for('user', username=username ) ) 
current_user.follow(user ) 
db.session.commit() 
flash('You are following {}!'.format(username) ) 
return redirect(url_for('user', username=username ) ) 


@app.route('/unfollow/<username>' ) 
@login_required 
def unfollow(username): 


user = User.query.filter_by(username=username) .first() 
if user is None: 
flash('User {} not found.'.format(username) ) 
return redirect(url_for('index')) 
if user == current_user: 
flash('You cannot unfollow yourself!') 
return redirect(url_for('user', username=username ) ) 
current_user.unfollow(user ) 
db.session.commit() 
flash('You are not following {}.'.format(username) ) 
return redirect(url_for('user', username=username ) ) 


FOAL A BA CART AP Xip HY KURLE LHS 


视图 函数 的 逻辑 不 言 而 喻 ， 但 要 注意 所 有 的 错误 检查 ， 以 防止 出 现 意外 的 问题 ， 并 尝试 在 出 
现 问 题 时 向 用 户 提供 有 用 的 信息 。 


RIS BI APALA BRB h EA PAER YP > VRE Pa Rie Fe IK 
注 的 操作 : 


<hi>User: {{ user.username }}</h1> 

{% if user.about_me %}<p>{{ user.about_me }}</p>{% endif %} 

{% if user.last_seen %}<p>Last seen on: {{ user.last_seen }}</p>{% endif %} 

<p>{{ user.followers.count() }} followers, {{ user.followed.count() }} followi 
ng.</p> 

{% if user == current_user %} 

<p><a href="{{ url_for('edit_profile') }}">Edit your profile</a></p> 

{% elif not current_user.is_following(user) %} 

<p><a href="{{ url_for('follow', username=user.username) }}">Follow</a></p> 

{% else %} 

<p><a href="{{ url_for('unfollow', username=user.username) }}">Unfollow</a></p 


{% endif %} 


用 户 个 人 主页 的 变更 ， 一 是 在 最 近 访 问 的 时 间 戳 之 下 添加 一 行 ， 以 显示 此 用 户 拥有 多 少 个 粉 
丝 和 关注 用 户 。 二 是 当 你 查看 自己 的 个 人 主页 时 出 现 的 Edit 链接 的 行 ， 可 能 会 变 成 以 下 三 种 
链接 之 一 : 


。 如 果 用 户 查看 他 (她 ) 自 己 的 个 人 主页 ， 仍 然 是 Edit" 链接 不 变 。 
e 如 果 用 户 查 看 其 他 并 未 关注 的 用 户 的 个 人 主页 ， 显 示 “Follow” 链 接 。 
@ 如 果 用 户 查 看 其 他 已 经 关注 的 用 户 的 个 人 主页 ， 显 示 “Unfollow” 链 接 。 


此 时 ， 你 可 以 运行 该 应 用 ， 创 建 一 些 用 户 并 测试 一 下 关注 和 取消 关注 用 户 的 功能 。 唯 一 需要 
记 住 的 是 ， 需 要 手动 键入 你 要 关注 或 取消 关注 的 用 户 的 个 人 主页 URL ， 因 为 目前 没有 办 法 查 
看 用 户 列表 。 例如， 如 果 你 想 关 注 susan ， 则 需要 在 浏览 器 的 地 址 栏 中 输 

入 http:/Nlocalhost:5000/user/susan 以 访问 该 用 户 的 个 人 主页 。 请 确保 你 在 测试 关注 和 取消 关 
注 的 时 候 ， 留 意 到 了 其 粉丝 和 关注 的 数量 变化 。 


我 应 该 在 应 用 的 主页 上 显示 用 户 动态 的 列表 ， 但 是 我 还 没有 完成 所 有 依赖 的 工作 ， 因 为 用 户 
不 能 发 表 动态 。 所 以 我 会 暂缓 这 个 页 面 的 完善 工作 ， 直 到 发 表 用 户 动态 功能 的 完成 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part IX: Pagination 
这 是 Flask Mega-Tutorial 系 列 的 第 九 部 分 ， 我 将 告诉 你 如 何 对 数据 列表 进行 分 页 。 


在 第 八 齐 我 已 经 做 了 几 个 数据 库 更 改 ， 以 支持 在 社交 网 络 非常 流行 的 "粉丝 "机 制 。 有 了 这 个 
功能 ， 接 下 来 我 准备 好 删除 一 开始 就 使 用 的 模拟 用 户 动 态 了 。 在 本 章 中 ， 应 用 将 开始 接受 来 
自用 户 的 动态 更 新 ， 并 将 其 发 布 到 网 站 首页 和 个 人 主页 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


发 布 用 户 动态 


让 我 们 从 简单 的 事情 开始 吧 。 首页 需要 有 一 个 表单 ， 用 户 可 以 在 其 中 键入 新 动态 。 我 创建 一 
个 表单 类 : 
class PostForm(FlaskForm): 
post = TextAreaField('Say something', validators=[ 


DataRequired(), Length(min=1, max=140)]) 
submit = SubmitField('Submit' ) 


然后 ， 我 将 该 表单 添加 到 网 站 首页 的 模板 中 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Hi, {{ current_user.username }}!</h1i> 


<form action=""_ method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.post.label }}<br> 
{{ form.post(cols=32, rows=4) }}<br> 
{% for error in form.post.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 
</p> 
<p>{{ form.submit() }}</p> 
</form> 
{% for post in posts %} 
<p> 
{{ post.author.username }} says: <b>{{ post.body }}</b> 
</p> 
{% endfor %} 
{% endblock %} 


模板 中 的 变更 和 处 理 以 前 的 表单 类 似 。 最 后 的 部 分 是 将 表单 处 理 逻 辑 添 加 到 视图 函数 中 : 


from app.forms import PostForm 
from app.models import Post 


@app.route('/', methods=['GET', 'POST']) 
@app.route('/index', methods=['GET', 'POST']) 
@login_required 
def index(): 
form = PostForm() 
if form.validate_on_submit(): 
post = Post(body=form.post.data, author=current_user) 
db.session.add(post) 
db.session.commit() 
flash('Your post is now live!') 
return redirect(url_for('index') ) 


posts = [ 
"author': {'username': 'John'}, 
"body': 'Beautiful day in Portland!' 
}, 
{ 
'author': {'username': 'Susan'}, 
"body': 'The Avengers movie was so cool!' 
} 


return render_template("index.html", title='Home Page', form=form, 
posts=posts) 


我 们 来 一 个 个 地 解读 该 视图 函数 的 变更 : 


© 导入 Post 和 postForm 类 

© 关联 到 index 视图 函数 的 两 个 路 由 都 新 增 接 受 post 请 求 ， 以 便 视图 函数 处 理 接收 的 表单 
数据 

o 处 理 表单 的 逻辑 会 为 post 表 插 入 一 条 新 的 数据 

© 模板 新 增 接受 form 对 象 ， 以 便 浑 染 文 本 输入 框 


在 继续 之 前 ， 我 想 提 一 些 与 Web 表 单 处 理 相关 的 重要 内 容 。 请 注意 ， 在 处 理 表单 数据 后 ， 我 
通过 发 送 重 定向 到 主页 来 结束 请 求 。 我 可 以 轻松 地 跳 过 重 定 向 ， 并 允许 函数 继续 向 下 进入 模 
板 泻 染 部 分 ， 因 为 这 已 经 是 主页 视图 函数 了 。 


么 ， 为 什么 重 定向 呢 ? 通过 重 定向 来 响应 Web 表 单 提交 产生 的 POST 请 求 是 一 种 标准 做 
这 有 助 于 缓解 在 Web 浏 览 器 中 执行 刷新 命令 的 烦恼 。 当 你 点 击 刷新 键 时 ， 所 有 的 网 页 浏 
ST 
刷新 将 重新 提交 表单 。 因为 这 不 是 预期 的 行为 ， 所 以 浏览 器 会 要 求 用 户 确认 重复 的 提交 
是 大 多 数 用 户 却 很 难 理解 浏览 器 询问 的 内 容 。 不 过 ， 如 果 一 个 post 请 求 被 重 定向 响应 ， 
器 现在 被 指示 发 送 GET 请 求 来 获取 重 定向 中 指定 的 页 面 ， 所 以 现在 最 后 一 个 请 求 不 再 
是 'POST' 请 求 了 ， 刷新 命令 就 能 以 更 可 预测 的 方式 工作 。 


这 个 简单 的 技巧 叫做 Post/Redirect/Get 模 式 。 它 避免 了 用 户 在 提交 网 页 表单 后 无 意 中 刷 新 
面 时 插入 重复 的 动态 。 


展示 用 户 动态 


如 果 你 还 记得 ， 我 创建 过 几 条 模拟 的 用 户 动态 ， 展 示 在 主页 已 经 有 一 段 时 间 了 。 这 些 模拟 对 
象 是 在 index 视图 函数 中 显 式 创建 的 一 个 简单 的 Python 列表 : 


posts = [ 
‘author': {'username': 'John'}, 
"body ' : ‘Beautiful day in Portland!' 
}, 
{ 
‘author': {'username': 'Susan'}, 
'body': 'The Avengers movie was so cool!' 
} 


但 是 现在 我 在 User 模型 中 有 了 followed posts() 方法 ， 它 可 以 返回 给 定 用 户 希 望 看 到 的 用 户 
动态 的 查询 结果 集 。 所 以 现在 我 可 以 用 真正 的 用 户 动态 闪 换 模拟 的 用 户 动 态 : 


@app.route('/', methods=['GET', 'POST']) 
@app.route('/index', methods=['GET', 'POST']) 
@login_required 
def index(): 
# i... 
posts = current_user.followed_posts().all() 
return render_template("index.html", title='Home Page', form=form, 
posts=posts) 


User 类 的 followed_posts 方法 返回 一 个 SQLAIchemy 查 询 对 象 ， 该 对 象 被 配置 为 从 数据 库 中 
获取 用 户 感 兴趣 的 用 户 动态 。 在 这 个 查询 中 调用 alo 会 触发 它 的 执行 ， 返 回 值 是 包含 所 有 
结果 的 列表 。 所 以 我 最 终 得 到 了 一 个 与 我 迄今 为 止 一 直 使 用 的 模拟 用 户 动 态 非常 相似 的 结 
构 。 它们 非常 接近 ， 模 板 甚至 不 需要 改变 。 


更 容易 地 发 现 和 关注 用 户 


相信 你 已 经 留意 到 了 ， 应 用 没有 一 个 很 好 的 途径 来 让 用 户 可 以 找到 其 他 用 户 进行 关注 。 实 际 
上 ， 现 在 根本 没有 办 法 在 页 面 上 查看 到 底 有 哪些 用 户 存在 。 我 将 会 使 用 少量 简单 的 变更 来 解 
决 这 个 问题 。 


我 将 会 创建 一 个 新 的 “发现 "页 面 。 该 页 面 看 起 来 像 是 主页 ， 但 是 却 不 是 只 显示 已 关注 用 户 的 动 
态 ， 而 是 展示 所 有 用 户 的 全 部 动态 。 新 增 的 发 现 视图 函数 如 下 : 


@app.route('/explore') 
@login_required 
def explore(): 
posts = Post.query.order_by(Post.timestamp.desc()).all() 
return render_template('index.html', title='Explore', posts=posts) 


你 有 没有 注意 到 这 个 视图 函数 中 的 奇怪 之 处 ? render_template() 引用 了 我 在 应 用 的 主页 面 中 
使 用 的 jindex.html 模 板 。 这 个 页 面 与 主页 非常 相似 ， 所 以 我 决定 重用 这 个 模板 。 但 与 主页 不 
同 的 是 ， 在 发 现 页 面 不 需要 一 个 发 表 用 户 动态 表单 ， 所 以 在 这 个 视图 函数 中 ， 我 没有 在 模板 


调用 中 包含 form 参数 9 


要 防止 index.html 模 板 在 尝试 呈现 不 存在 的 Web 表 单 时 崩溃 ， 我 将 添加 一 个 条 件 ， 只 在 传 入 表 
单 参数 后 才 会 呈现 该 表单 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Hi, {{ current_user.username }}!</h1> 
{% if form %} 
<form action="" method="post"> 
</form> 
{% endif %} 


{% endblock %} 


该 页 面 也 需要 添加 到 导航 栏 中 : 


<a href="{{ url_for('explore') }}">Explore</a> 


还 记得 我 在 第 六 章 中 介绍 的 用 于 个 人 主页 浑 染 用 户 动态 的 _posthtml/ 子 模板 吗 ? 这 是 一 个 包含 
在 个 人 主页 模板 中 的 小 模板 ， 它 独立 于 其 他 模板 ， 因 此 也 可 以 被 这 些 模板 调用 。 我 现在 要 做 
一 个 小 小 的 改进 ， 将 用 户 动 态 作 者 的 用 户 名 显示 为 一 个 链接 : 


<table> 
<tr valign="top"> 
<td><img src="{{ post.author.avatar(36) }}"></td> 
<td> 
<a href="{{ url_for('user', username=post.author.username) }}"> 
{{ post.author.username }} 


</a> 
says:<br>{{ post.body }} 
</td> 
</tr> 
</table> 


然后 在 主页 和 发 现 页 中 使 用 这 个 子 模板 来 泻 染 用 户 动态 : 


{% for post in posts %} 
{% include '_post.html' %} 
{% endfor %} 


子 模板 期 望 存在 一 个 名 为 post 的 变量 ， 才 能 正常 工作 。 该 变量 是 上 层 模板 中 通过 循环 产生 
的 。 


ta 


通过 这 些 细 小 的 变更 ， 应 用 的 用 户 体 验 得 到 了 大 大 的 提升 。 现 在 ， 用 户 可 以 访问 发 现 页 来 查 
看 陌生 用 户 的 动态 ， 并 通过 这 些 用 户 动态 来 关注 用 户 ， 而 需要 的 操作 仅仅 是 点 击 用 户 名 跳 转 
到 其 个 人 主页 并 点 击 关注 链接 。 令 人 叹为观止 1 对 吧 ? 


此 时 ， 我 建议 你 在 应 用 上 再 次 尝试 一 下 这 个 功能 ， 以 便 体 验 最 后 的 用 户 接口 的 完善 。 


Explore - Microblog 


一 GC 合 © localhost:5000/explore 
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. . 
Hi, john! 
E john says: 
Stuck in traffic. 6&9 
2 susan says: 
Beautiful day in Portland! 


【 习 miguel says: 
Hello, friends! 





用 户 动 态 的 分 页 
应 用 看 起 来 更 完善 了 ， 但 是 在 主页 显示 所 有 用 户 动态 迟早 会 出 问题 。 如 果 一 个 用 户 有 成 千 上 


万 条 关注 的 用 户 动态 时 ， 会 发 生 什么 ?你 可 以 想象 得 到 ， 管 理 这 么 大 的 用 户 动态 列表 将 会 变 
得 相当 绥 慢 和 低 效 。 


为 了 解决 这 个 问题 ， 我 会 将 用 户 动态 进行 分 页 。 这 意味 着 一 开始 显示 的 只 是 所 有 用 户 动态 的 
一 部 分 ， 并 提供 链接 来 访问 其 余 的 用 户 动态 。Flask-SQLAIchemy 的 paginate() 方法 原生 就 
支持 分 页 。 例 如 ， 我 想 要 获取 用 户 关注 的 前 20 个 动态 ， 我 可 以 将 all() 结束 调用 替换 成 如 下 
的 查询 : 


>>> user.followed_posts().paginate(1, 20, False).items 


Flask-SQLAIchemy 的 所 有 查询 对 象 都 支持 paginate 方法 ， 需 要 输入 三 个 参数 来 调用 它 : 


o 从 1 开始 的 页 码 
e 每 页 的 数据 量 
e 错误 处 理 布尔 标记 ， 如 果 是 True ， 当 请 求 范围 超出 已 知 范围 时 自动 引发 404 错 误 。 如 果 


是 False ， 则 会 返回 一 个 空 列 表 。 


paginate 方法 返回 一 个 pagination 的 实例 。 其 items 属性 是 请 求 内 容 的 数据 列 
表 。 Pagination 实例 还 有 一 些 其 他 用 途 ， 我 会 在 之 后 讨论 。 


现在 想 想 如 何在 index() 视图 函数 展现 分 页 呢 。 我 先 来 给 应 用 添加 一 个 配置 项 ， 以 表示 每 页 
展示 的 数据 列表 长 度 吧 。 
class Config(object): 


# wa, 
POSTS_PER_PAGE = 3 


存储 这 些 应 用 范围 的 “可 控 机 关 ” 到 配置 文件 是 一 个 好 主意 ， 因 为 这 样 我 调整 时 只 需 去 一 个 地 
方 。 在 最 终 的 应 用 中 ， 每 页 显示 的 数据 将 会 大 于 三 ， 但 是 对 于 测试 而 言 ， 使 用 小 数字 很 方 
便 。 

接 下 来 ， 我 需要 决定 如 何 将 页 码 并 入 到 应 用 URL 中 。 一 个 相当 常见 的 方法 是 使 用 查询 字符 串 
参数 来 指定 一 个 可 选 的 页 码 ， 如 果 没 有 给 出 则 默认 为 页 面 1。 以 下 是 一 些 示例 网 址 ， 显 示 了 我 
将 如 何 实现 这 一 点 : 


e 第 1 页 ， 隐 含 : http:Nlocalhost:5000/index 
。 第 1 页 ， 显 式 : http-//ocalhost:5000/index?page=1 
。 第 3 页 : http://ocalhost:5000/index?page=3 


要 访问 查询 字符 串 中 给 出 的 参数 ， 我 可 以 使 用 Flask 的 request.args 对 象 。 你 已 经 在 第 五 章 中 
看 到 了 这 种 方法 ， 我 用 Flask-Login 实 现 了 用 户 登 录 的 可 以 包含 一 个 next 查询 字符 串 参 数 的 
URL ° 


给 主页 和 发 现 页 的 视图 函数 添加 分 页 的 代码 变更 如 下 : 


@app.route('/', methods=['GET', 'POST']) 
@app.route('/index', methods=['GET', 'POST']) 
@login_required 
def index(): 
# ... 
page = request.args.get('page', 1, type=int) 
posts = current_user.followed_posts().paginate( 
page, app.config['POSTS_PER_PAGE'], False) 
return render_template('index.html', title='Home', form=form, 
posts=posts.items) 


@app.route('/explore') 
@login_required 
def explore(): 
page = request.args.get('page', 1, type=int) 
posts = Post.query.order_by(Post.timestamp.desc()).paginate( 
page, app.config['POSTS_PER_PAGE'], False) 
return render_template("index.html", title='Explore', posts=posts.items) 


通过 这 些 更 改 ， 这 两 个 路 由 决定 了 要 显示 的 页 码 ， 可 以 从 page 查询 字符 串 参 数 获得 或 是 默认 
值 1。 然后 使 用 paginate() 方法 来 检索 指定 范围 的 结果 。 决定 页 面 数据 列表 大 小 
的 POSTS_PER_PAGE 配置 项 是 通过 app.config 对 象 中 获取 的 。 


请 注意 ， 这 些 更 改 非常 简单 ， 每 次 更 改 都 只 会 影响 很 少 的 代码 。 我 试图 在 编写 应 用 每 个 部 分 
的 时 候 ， 不 做 任何 有 关 其 他 部 分 如 何 工作 的 假设 ， 这 使 我 可 以 编写 更 易于 扩展 和 测试 的 且 兼 
有 具 模块 化 和 健壮 性 的 应 用 ， 并 且 不 太 可 能 失败 或 出 现 BUG 。 


来 尝试 下 分 页 功能 吧 。 首先 确保 你 有 三 条 以 上 的 用 户 动态 。 在 发 现 页 面 中 更 方便 测试 ， 因 为 
该 页 面 显示 所 有 用 户 的 动态 。 你 现在 只 会 看 到 最 近 的 三 条 用 户 动态 。 如 果 你 想 看 接 下 来 的 三 
E 


E nl O 


接 下 来 的 改变 是 在 用 户 动态 列表 的 底部 添加 链接 ， 允 许 用 户 导 航 到 下 一 页 或 上 一 页 。 还 记得 
我 曾 提 到 过 paginate() 的 返回 是 pagination 类 的 实例 吗 ? 到 目前 为 止 ， 我 已 经 使 用 了 此 对 
象 的 items 属性 ， 其 中 包含 为 所 选 页 面 检索 的 用 户 动态 列表 。 但 是 这 个 分 页 对 象 还 有 一 些 其 
他 的 属性 在 构建 分 页 链接 时 很 有 用 : 


@ has_next : 当 前 页 之 后 存在 后 续 入 页 面 时 为 nm 
e has prev: ŽA RŽ AAA ER ON AA 
@ next_num : 十 一 页 的 页 码 





e prev_num : 上 一 页 的 页 码 
有 了 这 四 个 元 素 ， 我 就 可 以 生成 上 一 页 和 下 一 页 的 链接 并 将 其 传 入 模板 以 泻 染 


@app.route('/', methods=['GET', 'POST']) 
@app.route('/index', methods=['GET', 'POST']) 
@login_required 
def 2 
# 
page = request.args.get('page', 1, type=int) 
posts = current_user.followed_posts().paginate( 
page, app.config['POSTS_PER_PAGE'], False) 
next_url = url_for('index', page=posts.next_num) \ 
if posts.has_next else None 
prev_url = url_for('index', page=posts.prev_num) \ 
if posts.has_prev else None 
return render_template('index.html', title='Home', form=form, 
posts=posts.items, next_url=next_url, 
prev_url=prev_url) 


@app.route('/explore' ) 
@login_required 
def explore(): 
page = request.args.get('page', 1, type=int) 
posts = Post.query.order_by(Post.timestamp.desc()).paginate( 
page, app.config['POSTS_PER_PAGE'], False) 
next_url = url_for('explore', page=posts.next_num) 和 
if posts.has_next else None 
prev_url = url_for('explore', page=posts.prev_num) 和 
if posts.has_prev else None 
return render_template("index.html", title='Explore', posts=posts.items, 
next_url=next_url, prev_url=prev_ur1l) 


这 两 个 视图 函数 中 的 next_url 和 prev_url 只 有 在 该 方向 上 存在 一 个 页 面 时 ， 才 会 被 设置 为 
由 url_for() 返回 的 URL。 如 果 当 前 页 面 位 于 用 户 动 态 集合 的 末尾 或 者 开头 ， 那 

么 Pagination 实例 的 has_next 或 has_prev 属性 将 为 "False'， 在 这 文 种 情 况 下 ， 将 设置 该 方向 
的 链接 为 None 。 


url_for() 函数 的 一 个 有 趣 的 地 方 是 ， 你 可 以 添加 任何 关键 字 参 数 ， 如 果 这 些 参 数 的 名 字 没 
有 直接 在 URL 中 匹配 使 用 ， 那么 Flask 将 它们 设置 为 URL 的 查询 字符 串 参 数 。 


现在 让 我 们 把 它们 泻 染 在 jaex.hntmm/ 模 板 上 ， 就 在 用 户 动态 列表 的 正 下 方 : 


we: 


{% for post in posts %} 
{% include '_post.html' %} 
{% endfor %} 
{% if prev_url %} 
<a href="{{ prev_url }}">Newer posts</a> 
{% endif %} 
{% if next_url %} 
<a href="{{ next_url }}">Older posts</a> 
{% endif %} 


主页 和 发 现 页 都 添加 了 分 页 链接 。 第 一 个 链接 标记 为 “Newer posts”， 并 指向 前 一 页 (请 记 
住 ， 我 显示 的 用 户 动态 按时 间 的 倒序 来 排序 ， 所 以 第 一 页 是 最 新 的 内 容 ) 。 第 二 个 链接 标记 
A“Older posts”， 并 指向 下 一 页 的 帖子 。 如 果 这 两 个 链接 中 的 任何 一 个 都 是 None ， 则 通过 条 
件 过 滤 将 其 从 页 面 中 省 略 。 


Explore - Microblog 
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Hi, susan! 


E john says: 
one more 
john says: 
Stuck in traffic. @) 


2 susan says: 
Beautiful day in Portland! 


Newer posts Older posts 


个 人 主页 中 的 分 页 


主页 分 页 已 经 完成 ， 但 是 ， 个 人 主页 中 也 有 一 个 用 户 动态 列表 ， 其 中 只 显示 个 人 主页 拥有 者 
的 动态 。 为 了 保持 一 致 ， 个 人 主页 也 应 该 实现 分 页 ， 以 匹配 主页 的 分 页 样式 。 


我 开始 更 新 个 人 主页 视图 函数 ， 其 中 仍然 有 一 个 模拟 用 户 动态 的 列表 。 


@app.route('/user/<username>' ) 
@login_required 
def user(username): 
user = User.query.filter_by(username=username) .first_or_404() 
page = request.args.get('page', 1, type=int) 
posts = user.posts.order_by(Post.timestamp.desc()).paginate( 
page, app.config['POSTS_PER_PAGE'], False) 
next_url = url_for('user', username=user.username, page=posts.next_num) \ 
if posts.has_next else None 
prev_url = url_for('user', username=user.username, page=posts.prev_num) \ 
if posts.has_prev else None 
return render_template('user.html', user=user, posts=posts.items, 
next_url=next_url, prev_url=prev_ur1) 


为 了 得 到 用 户 的 动态 列表 ， 我 利用 了 user 模型 中 已 经 定义 好 的 user.posts 一 对 多 关系 。 我 
执行 该 查询 并 添加 一 个 order_by O 子 句 ， 以 便 我 首先 得 到 最 新 的 用 户 动态 ， 然 后 完全 按照 
我 对 主页 和 发 现 页 面 中 的 用 户 动态 所 做 的 那样 进行 分 页 。 请 注意 ， 由 url_for() B HA AY 
分 页 链接 需要 额外 的 username 参数 ， 因 为 它们 指向 个 人 主页 ， 个 人 主页 依赖 用 户 名 作为 URL 
的 动态 组 件 。 


最 后 ， 对 Userhtm/ 模 板 的 更 改 与 我 在 主页 上 所 做 的 更 改 相同 : 


{% for post in posts %} 
{% include '_post.html' %} 
{% endfor %} 
{% if prev_url %} 
<a href="{{ prev_url }}">Newer posts</a> 
{% endif %} 
{% if next_url %} 
<a href="{{ next_url }}">Older posts</a> 
{% endif %} 


完成 对 分 页 功能 的 实验 后 ， 可 以 将 posts peR PAGE 配置 项 设置 为 更 合理 的 值 : 


class Config(object): 
# i... 
POSTS_PER_PAGE = 25 


本 文 翻 译 自 The Flask Mega-Tutorial Part X: Email Support 


这 是 Flask Mega-Tutorial 系 列 的 第 十 部 分 ， 在 其 中 我 将 告诉 你 ， 应 用 如 何 向 你 的 用 户 发 送 电子 
邮件 ， 以 及 如 何在 电子 邮件 支持 之 上 构建 密码 重 置 功能 。 


现在 ， 应 用 在 数据 库 方面 做 得 相当 不 错 ， 所 以 在 本 章 中 ， 我 想 抛 开 这 个 主题 ， 开 始 添加 发 送 
电子 邮件 的 功能 ， 这 是 大 多 数 Web 应 用 必需 的 另 一 个 重要 部 分 。 


为 什么 应 用 需要 发 送 电子 邮件 给 用 户 ? 原因 很 多 ， 但 其 中 一 个 常见 的 原因 是 解决 与 认证 相关 
的 问题 。 在 本 章 中 ， 我 将 为 忘记 密码 的 用 户 添加 密码 重 置 功能 。 当 用 户 请 求 重 置 密码 时 ， 应 
用 将 发 送 包 含 特制 链接 的 电子 邮件 。 用 户 然后 需要 点 击 该 链接 才能 访问 设置 新 密码 的 表单 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


Flask-Mail 简 介 


和 


就 实际 的 邮件 发 送 而 言 ，Flask 有 一 个 名 为 Flask-Mail 的 流行 插件 ， 可 以 使 任务 变 得 非常 从 
单 。 和 往常 一 样 ， 该 插件 是 用 pip 安 装 的 : 


B 


(venv) $ pip install flask-mail 


密码 重 置 链接 将 包含 有 一 个 安全 令 牌 。 为 了 生成 这 些 令 牌 ， 我 将 使 用 JSON Web Tokens? € 
也 有 一 个 流行 的 Python 包 : 


(venv) $ pip install pyjwt 


Flask-Mail 插 件 是 通过 app.config 对 象 来 配置 的 。 还 记得 在 第 七 章 中 ， 我 添加 了 用 于 在 生产 
环境 中 发 生 错误 时 发 送 电 子 邮 件 的 配置 项 ? 当时 我 没有 告诉 你 ， 不 过 ， 我 选择 的 配置 变量 都 是 
Flask-Mail 的 需求 的 ， 所 以 不 需要 任何 额外 的 工作 ， 配 置 的 活 已 经 完工 。 
像 大 多 数 Flask 播 件 一 样 ， 你 需要 在 Flask 应 用 创建 之 后 创建 一 个 邮件 实例 。 本 处 ， mail 是 
类 Mail 的 一 个 实例 : 

HS 

from flask_mail import Mail 

app = Flask(__name_) 

# 


mail = Mail(app) 


第 七 章 中 我 提 到 过 ， 测 试 发 送 电 子 邮件 的 方式 有 两 种 。 如 果 你 想 使 用 一 个 模拟 的 电子 邮件 服 
务 器 ，Python 提 供 了 一 个 非常 好 用 的 方法 ， 你 可 以 使 用 下 面 的 命令 在 第 二 个 终端 中 启动 它 : 


(venv) $ python -m smtpd -n -c DebuggingServer localhost:8025 


要 配置 此 服务 器 ， 需 要 设置 两 个 环境 变量 : 


(venv) $ export MAIL_SERVER=localhost 
(venv) $ export MAIL_PORT=8025 


fo R AR A 2 LRA POR MR RRA ALY EPRA Se 那么 你 只 需要 为 它 设 
置 MAIL_SERVER ` MAIL PORT ` MAIL USE TLS ` MAIL_USERNAME 和 MAIL_PASSWORD 环境 变量 


如 果 你 想 要 快速 解决 方案 ， 可 以 使 用 Gmail 帐户 发 送 电子 邮件 ， 并 使 用 以 下 设置 : 


(venv) $ export MAIL_SERVER=smtp.googlemail.com 
(venv) $ export MAIL_PORT=587 

(venv) $ export MAIL_USE_TLS=1 

(venv) $ export MAIL_USERNAME=<your -gmail-username> 
(venv) $ export MAIL_PASSWORD=<your -gmail-password> 


如 果 你 使 用 的 是 Microsoft Windows， 则 需要 在 上 面 的 每 个 export 语句 中 将 export 替换 
为 set 。 


Gmail 帐户 中 的 安全 功能 可 能 会 阻止 应 用 通过 它 发 送 电子 邮件 ， 除 非 你 明确 允许 "安全 性 较 低 
的 应 用 程序 "访问 你 的 Gmail 帐户 。 可 以 阅读 此 处 来 了 解 具体 情 况 ， 如 果 你 担心 帐户 的 安全 
性 ， 可 以 创建 一 个 辅助 邮箱 帐户 ， 配 置 它 来 仅 用 于 测试 电子 邮件 功能 ， 或 者 你 可 以 暂时 启用 
允许 不 太 安全 的 应 用 程序 来 运行 此 测试 ， 完 成 后 恢复 为 默认 值 。 


Flask-Mail 的 使 用 


为 了 学 习 Flask-Mail 如 何 工作 ， 我 将 向 你 展示 如 何 用 shell 发 送 电 子 邮 件 。 那 么 ， 
行 flask shell 以 激活 Python ， 然 后 运行 下 面 的 命 


>>> from flask_mail import Message 

>>> from app import mail 

>>> msg = Message('test subject', sender=app.config['ADMINS'][0], 
... recipients=['your-email@example.com']) 

>>> msg.body = 'text body' 

>>> msg.html = '<h1i>HTML body</hi>' 

>>> mail.send(msg) 


上 面 的 代码 片段 将 发 送 一 个 电子 邮件 到 你 在 recipients 参数 中 设置 的 电子 邮件 地 址 列表 。 发 
件 人 配置 项 我 在 第 七 章 中 已 经 配置 过 了 ， 是 amns 。 该 电子 邮件 将 具有 纯 文 本 和 HTML 版 
本 ， 所 以 根据 你 的 电子 邮件 客户 端的 配置 ， 可 能 会 看 到 它们 之 中 的 其 中 之 一 。 


如 你 所 见 ， 相 当 简 单 。 现 在 让 我 们 将 电子 邮件 整合 到 应 用 中 。 


简单 的 电子 邮件 框 染 


我 将 从 编写 一 个 发 送 电子 邮件 的 帮助 函数 开始 ， 这 个 函数 基本 上 是 上 一 节 中 shell 函 数 的 通用 
版 本 。 我 将 把 这 个 函数 放 在 一 个 名 为 app/email.py 的 新 模块 中 : 


from flask_mail import Message 
from app import mail 


def send_email(subject, sender, recipients, text_body, html_body): 
msg = Message(subject, sender=sender, recipients=recipients) 
msg.body = text_body 
msg.html = html_body 
mail.send(msg) 


Flask-Mail 支 持 一 些 我 不 在 这 里 使 用 的 功能 ， 如 抄 送 和 密 件 抄 送 列表 。 如 果 你 对 这 些 选项 感 兴 
趣 ， 务 必 查 阅 Flask-Mail 文 档 。 


Ta RE a HAZ 
我 上 面 提 到 过 ， 用 户 有 权利 重 置 密码 。 因 此 我 将 在 登录 页 面 提供 一 个 链接 : 


<p> 
Forgot Your Password? 


<a href="{{ url_for('reset_password_request') }}">Click to Reset It</a> 
</p> 


当 用 户 点 击 链 接 时 ， 会 出 现 一 个 新 的 Web 表 单 ， 要 求 用 户 输入 注册 的 电子 邮件 地 址 ， 以 启动 


密码 重 置 过 程 。 这 里 是 表单 类 : 


class ResetPasswordRequestForm(FlaskForm): 
email = StringField('Email', validators=[DataRequired(), Email()]) 
submit = SubmitField('Request Password Reset' ) 


这 里 是 相应 的 HTML 模 板 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Reset Password</h1i> 


<form action="" method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.email.label }}<br> 
{{ form.email(size=64) }}<br> 
{% for error in form.email.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p>{{ form.submit() }}</p> 

</form> 
{% endblock %} 


当然 也 需要 一 个 视图 函数 来 处 理 表单 : 


from app.forms import ResetPasswordRequestForm 
from app.email import send_password_reset_email 


@app.route('/reset_password_request', methods=['GET', 'POST']) 
def reset_password_request(): 
if current_user.is_authenticated: 
return redirect(url_for('index')) 
form = ResetPasswordRequestForm( ) 
if form.validate_on_submit(): 
user = User.query.filter_by(email=form.email.data).first() 
if user: 
send_password_reset_email(user ) 
flash('Check your email for the instructions to reset your password') 
return redirect(url_for('login')) 
return render_template('reset_password_request.html', 
title='Reset Password', form=form) 


该 视图 函数 与 其 他 的 表单 处 理 视 图 函数 非常 相似 。 我 从 确保 用 户 没 有 登录 开始 ， 如 果 用 户 登 
录 ， 那 么 使 用 密码 重 置 功能 就 没有 意义 ， 所 以 我 重 定向 到 主页 。 


当 表 格 被 提交 并 验证 通过 ， 我 使 用 表格 中 的 用 户 提 供 的 电子 邮件 来 查找 用 户 。 如 果 我 找到 用 
户 ， 就 发 送 一 封 密码 重 置 电 子 邮 件 。 我 执行 此 操作 使 用 的 send_password_reset_email() 辅助 
函数 ， 将 在 下 面向 你 展示 。 


电子 邮件 发 送 后 ， 我 会 闪现 一 条 消息 ， 指 示 用 户 查看 电子 邮件 以 获取 进一步 说 明 ， 然 后 重 定 
向 回 登 录 页 面 。 你 可 能 会 注意 到 ， 即 使 用 户 提供 的 电子 邮件 不 存在 ， 也 会 显示 闪现 的 消息 ， 
这 样 的 话 ， 客 户 端 就 不 能 用 这 个 表单 来 判断 一 个 给 定 的 用 户 是 否 已 注册 。 


密码 重 置 令 牌 


在 实现 send_password_reset_email() 函数 之 前 ? 我 需要 一 种 方法 来 生成 密码 重 置 链接 ， 它 将 
被 通过 电子 邮件 发 送 给 用 户 。 当 链 接 被 点 击 时 ， 将 为 用 户 展现 设置 新 密码 的 页 面 。 这 个 计划 
中 辣 手 的 部 分 是 确保 只 有 有 效 的 重 置 链接 可 以 用 来 重 置 帐 户 的 密码 。 


生成 的 链接 中 会 包含 令 牌 ， 它 将 在 允许 密码 变更 之 前 被 验证 ， 以 证 明 请 求 重 置 密码 的 用 户 是 
通过 访问 重 置 密码 邮件 中 的 链接 而 来 的 。JSON Web Token (JWT) 是 这 类 令 牌 处 理 的 流行 
标准 。JWTs 的 优点 是 它 是 自 成 一 体 的 ， 不 但 可 以 生成 令 牌 ， 还 提供 对 应 的 验证 方法 。 


如 何 运 行 JWTs? 让 我 们 通过 Python shell 来 学 习 一 下 : 


>>> import jwt 
>>> token = jwt.encode({'a': 'b'}, 'my-secret', algorithm='HS256' ) 


>>> token 
b' eyJOeXALi0i JKV1QiLCJhbGci0iJIUZI1NiJ9.eyJhIjoiYiJ9.dvOoS580BDHiuSHD4uWw88snf JikhYAXc_sfU 
HqimDi4Go' 
>>> jwt.decode(token, 'my-secret', algorithms=['HS256']) 
EAS ` 1 b $ } 


{'a' : 'b'} 字典 是 要 写 入 令 牌 的 示例 有 效 载荷 。 为 了 使 令 牌 安全 ， 需 要 提供 一 个 秘密 密 钥 用 
于 创建 加 密 签 名 。 在 这 个 例子 中 ， 我 使 用 了 字符 串 'my-secret' ， 但 是 在 应 用 中 ， 我 将 使 用 
配置 中 的 SECRET_KEY ° algorithm 参数 指定 使 用 什么 算法 来 生成 令 牌 ， 而 Hs256 是 应 用 最 广 


泛 的 算法 。 


如 你 所 见 ， 得 到 的 令 牌 是 一 长 串 字 符 。 但 是 不 要 认为 这 是 一 个 加 密 的 令 牌 。 令 有 牌 的 内 容 ， 色 
括 有 效 载荷 ， 可 以 被 任何 人 轻易 解码 (不 相信 我 ? 复制 上 面 的 令 牌 ， 然 后 粘贴 在 JWT 调 试 器 
上 就 可 以 看 到 它 的 内 容 ) 。 使 令 牌 安全 的 是 ， 有 效 载荷 是 被 签名 的 。 如 果 有 人 试图 伪造 或 莹 
改 令 牌 中 的 有 效 载 荷 ， 则 签名 将 会 无 效 ， 并 且 生 成 新 的 签名 依赖 秘密 密 钥 。 令 牌 验证 通过 
时 ， 有 效 负 载 的 内 容 将 被 解码 并 返回 给 调用 者 。 如 果 令 牌 的 签名 验证 通过 ， 有 效 载 荷 才 可 以 
被 认为 是 可 信 的 。 


我 要 用 于 密码 重 置 令 牌 的 有 效 载荷 格式 

为 {'reset_password' : user_id，'exp' : token_expiration} ° exp 字段 是 JWTS 的 标准 ， 如 果 它 
存在 ， 则 表示 令 牌 的 到 期 时 间 。 如 果 一 个 令 牌 有 一 个 有 效 的 签名 ， 但 是 它 已 经 过 期 ， 那 么 它 
也 将 被 认为 是 无 效 的 。 对 于 密码 重 置 功能 ， 我 会 给 这 些 令 牌 10 分 钟 的 有 效 期 。 


当 用 户 点 击 电 子 邮件 链接 时 ， 令 牌 将 被 作为 URL 的 一 部 分 发 送 回应 用 ， 处 理 这 个 URL 的 视图 
函数 首先 要 做 的 就 是 验证 它 。 如 果 签 名 是 有 效 的 ， 则 可 以 通过 存储 在 有 效 载 荷 中 的 ID 来 识别 
AP o 一 旦 得 知 用 户 的 身份 ， 应 用 可 以 要 求 一 个 新 的 密码 ， 并 将 其 设置 在 用 户 的 帐户 上 。 


由 于 这 些 令 牌 属于 用 户 ， 因 此 我 将 在 user 模型 中 编写 令 牌 生成 和 验证 的 方法 : 


from time import time 
import jwt 
from app import app 


class User(UserMixin, db.Model): 
# i... 


def get_reset_password_token(self, expires_in=600): 
return jwt.encode( 
{'reset_password': self.id, 'exp': time() + expires_in}, 
app.config['SECRET_KEY'], algorithm='HS256').decode('utf-8') 


@staticmethod 
def verify_reset_password_token( token): 
try: 
id = jwt.decode(token, app.config['SECRET_KEY'], 
algorithms=['HS256'])['reset_password' ] 
except: 
return 
return User.query.get(id) 


get_reset_password_token() 有 函数 以 字符 串 形式 生成 一 个 JWT 令 牌 。 请 注 
意 ” decode('utf-8') 是 必须 的 ， 因 为 jwt .encode() 函数 将 令 牌 作为 字 节 序列 返回 ’ 但 是 在 应 
用 中 将 令 牌 表示 为 字符 串 更 方便 。 


verify_reset_password_token() 是 一 个 静态 方法 ， 这 意味 着 它 可 以 直接 从 类 中 调用 。 静态 方 
法 与 类 方法 类 似 ， 唯 一 的 区 别 是 静态 方法 不 会 接收 类 作为 第 一 个 参数 。 这 个 方法 需要 一 个 令 
牌 ， 并 尝试 通过 调用 PyJWT 的 jwt.decode() 函数 来 解码 它 。 如 果 令 牌 不 能 被 验证 或 已 过 期 ， 
将 会 引发 异常 ， 在 这 种 情况 下 ， 我 会 捕获 它 以 防止 出 现 错误 ， 然 后 将 None 返回 给 调用 者 。 
如 果 令 牌 有 效 ， 那么 来 自 AEA BH 载 的 reset_password 的 值 就 是 用 户 的 ID ， 所 以 我 可 以 加 
载 用 户 并 返回 它 。 


RGAE BLS OB 


现在 我 有 了 令 牌 ， 可 以 生成 密码 重 置 电子 邮件 ° send_password_reset_email() 函数 依赖 于 上 
面 写 的 send_email() AX 


from flask import render_template 
from app import app 


# ... 


def send_password_reset_email(user): 
token = user.get_reset_password_token() 
send_email('[Microblog] Reset Your Password', 
sender=app.config['ADMINS'][0], 
recipients=[user.email], 
text_body=render_template('email/reset_password.txt', 
user=user, token=token), 
html_body=render_template('email/reset_password.html', 
user=user, token=token) ) 


这 个 函数 中 有 趣 的 部 分 是 电子 邮件 的 文本 和 HTML 内 容 是 使 用 熟悉 的 render_template() 函数 
从 模板 生成 的 。 模 板 接 收 用 户 和 令 牌 作为 参数 ， 以 便 可 以 生成 个 性 化 的 电子 邮件 消息 。 以 下 
是 重 置 密码 电子 邮件 的 文本 模板 : 


Dear {{ user.username }}, 

To reset your password click on the following link: 

{{ url_for('reset_password', token=token, _external=True) }} 

If you have not requested a password reset simply ignore this message. 
Sincerely, 


The Microblog Team 


这 是 更 美观 的 的 HTML 版 本 : 


<p>Dear {{ user.username }},</p> 
<p> 
To reset your password 
<a href="{{ url_for('reset_password', token=token, _external=True) }}"> 
click here 
</a>. 
</p> 
<p>Alternatively, you can paste the following link in your browser's address bar:</p> 
<p>{{ url_for('reset_password', token=token, _external=True) }}</p> 
<p>If you have not requested a password reset simply ignore this message.</p> 
<p>Sincerely, </p> 
<p>The Microblog Team</p> 


请 注意 ， 这 两 个 电子 邮件 模板 中 的 url_for() 调用 中 引用 的 reset_password 路 由 尚 不 存在 ， 
这 将 在 下 一 节 中 添加 。 


© a Pe 


当 用 户 点 击 电子 邮件 链接 时 ， 会 触发 与 此 功能 相关 的 第 二 个 路 由 。 这 是 密码 重 置 视图 函数 : 


from app.forms import ResetPasswordForm 


@app.route('/reset_password/<token>', methods=['GET', 'POST']) 
def reset_password(token): 
if current_user.is_authenticated: 
return redirect(url_for('index')) 
user = User.verify_reset_password_token( token) 
if not user: 
return redirect(url_for('index')) 
form = ResetPasswordForm() 
if form.validate_on_submit(): 
user .set_password( form. password.data) 
db.session.commit() 
flash('Your password has been reset.') 
return redirect(url_for('login')) 
return render_template('reset_password.html', form=form) 


在 这 个 视图 函数 中 ， 我 首先 确保 用 户 没 有 登录 ， 然 后 通过 调用 user 类 的 令 牌 验证 方法 来 确定 
用 户 是 谁 。 如 果 令 牌 有 效 ， 则 此 方法 返回 用 户 ; 如 果 不 是 ， 则 返回 none ， 并 将 重 定向 到 主 
m o 


N 


如 果 令 牌 是 有 效 的 ， 那 么 我 向 用 户 呈 现 第 二 个 表单 ， 需 要 用 户 其 中 输入 新 密码 。 这 个 表单 的 
处 理 方 式 与 以 前 的 表单 类 似 ， 表 单 提交 验证 通过 后 ， 我 调用 user 类 的 set_password() 方法 来 
更 改 密码 ， 然 后 重 定向 到 登录 页 面 ， 以 便 用 户 登 录 。 


这 是 ResetpasswordForm 类 : 


class ResetPasswordForm(FlaskForm): 
password = PasswordField('Password', validators=[DataRequired()]) 


password2 = PasswordField( 
"Repeat Password', validators=[DataRequired(), EqualTo('password')]) 
submit = SubmitField('Request Password Reset') 


这 是 相应 的 HTML 模 板 : 


{% extends "base.html" %} 


{% block content %} 
<hi>Reset Your Password</h1i> 


<form action="" method="post"> 
{{ form.hidden_tag() }} 
<p> 


{{ form.password.label }}<br> 
{{ form. password(size=32) }}<br> 
{% for error in form.password.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p> 
{{ form.password2.label }}<br> 
{{ form. password2(size=32) }}<br> 
{% for error in form.password2.errors %} 
<span style="color: red;">[{{ error }}]</span> 
{% endfor %} 

</p> 

<p>{{ form.submit() }}</p> 

</form> 
{% endblock %} 


密码 重 置 功 能 现 已 完成 ， 一 定 要 多 尝试 几 次 。 


异步 电子 邮件 


如 果 你 正在 使 用 Python 提供 的 模拟 电子 邮件 服务 器 ， 可 能 没有 注意 到 这 一 点 ， 那 就 是 发 送 电 
子 邮 件 会 大 大 减 慢 应 用 的 速度 ， 原 因 是 发 送 电子 邮 件 时 所 发 生 的 和 电子 邮件 服务 器 的 网 络 交 
互 。 通 常 需要 几 秒 钟 的 时 间 才 能 收 到 电子 邮件 ， 如 果 收 件 人 的 电子 邮件 服务 器 速度 较 慢 ， 或 
者 收 件 人 有 多 个 ， 则 可 能 会 更 久 。 


FA ERB send_email() 函数 是 异步 的 。 那 是 什么 意思 ae ea 文 个 函数 被 调用 时 ， 
发 送 邮件 的 任务 被 安排 在 后 台 进 行 ， 释 放 send_email() 函数 以 立即 返回 ， 以 便 应 用 可 以 在 发 
送 邮件 的 同时 继续 运行 。 


Python 实际 上 有 多 种 方式 支持 运行 异步 任务 ， threading 和 multiprocessing 模块 都 可 以 做 到 
动 一 个 后 台 线 程 ， 比 开始 一 个 全 新 的 进程 需要 的 资源 少 得 多 ， 所 
以 我 打算 采用 这 种 方法 : 


from threading import Thread 
# ,,， 


def send_async_email(app, msg): 
with app.app_context(): 
mail.send(msg) 


def send_email(subject, sender, recipients, text_body, html_body): 
msg = Message(subject, sender=sender, recipients=recipients) 
msg.body = text_body 
msg.html = html_body 
Thread(target=send_async_email, args=(app, msg)).start() 


send_async_email 函数 现在 运行 在 后 台 线 程 中 ， 它 通过 send_email() 的 最 后 一 行 中 

的 Thread() 类 来 调用 。 有 了 这 个 改变 ， 电 子 邮件 的 发 送 将 在 线程 中 运行 ， 并 且 当 进程 完成 
时 ， 线 程 将 结束 并 自行 清理 。 如 果 你 已 经 配置 了 一 个 真正 的 电子 邮件 服务 器 ， 当 你 按 下 密码 
重 时 请 求 表单 上 的 提交 按钮 时 ， 肯 定 会 注意 到 访问 速度 的 提升 。 


你 可 能 预期 只 有 mg 参数 会 被 发 送 到 线程 ， 但 正如 你 在 代码 中 所 看 到 的 那样 ， 我 也 传 入 了 应 
用 实例 。 使 用 线程 时 ， 需 要 牢记 Flask 的 一 个 重要 设计 方面 。Flask 使 用 上 下 文 来 避免 必须 跨 
函数 传递 参数 。 我 不 打算 详细 讨论 这 个 问题 ， 但 是 需要 知道 的 是 ， 有 两 种 类 型 的 上 下 文 ， 即 
应 用 上 下 文 和 请 求 上 下 文 。 在 大 多 数 情况 下 ， 这 些 上 下 文 由 框架 自动 管理 ， 但 是 当 应 用 启动 
自 定义 线程 时 ， 可 能 需要 手动 创建 这 些 线程 的 上 下 文 。 


许多 Flask 插 件 需要 应 用 上 下 文才 能 工作 ， 因 为 这 使 得 他 们 可 以 在 不 传递 参数 的 情况 下 找到 
Flask 应 用 实例 。 这 些 插件 需要 知道 应 用 实例 的 原因 是 因为 它们 的 配置 存储 在 app.config 对 象 
中 ， 这 正 是 Flask-Mail 的 情况 。 mail.send() 方法 需要 访问 电子 邮件 服务 器 的 配置 值 ， 而 这 必 
须 通过 访问 应 用 属性 的 方式 来 实现 。 使 用 with app.app_context() 调用 创建 的 应 用 上 下 文 使 
得 应 用 实例 可 以 通过 来 自 Flask 的 current_app 变量 来 进行 访问 。 


A XË Á The Flask Mega-Tutorial Part XI: Facelift 


这 是 Flask Mega-Tutorial 系 列 的 第 十 一 部 分 ， 我 将 告诉 你 如 何 用 基于 Bootstrap 用 户 界 面 框架 
的 新 模板 替换 基础 的 HTML 模 板 。 


你 把 玩 Microblog 应 用 也 有 一 段 时 间 了 ， 所 以 我 相信 你 已 经 注意 到 ， 我 没有 花 太 多 时 间 来 美化 
它 ， 说 得 更 具体 点 ， 我 根本 没有 花 时 间 。 所 有 的 模板 只 使 用 了 基础 样式 ， 没 有 任何 自 定义 的 
展现 。 这 对 于 我 来 说 却 非常 有 用 ， 因 为 我 可 以 专注 于 应 用 的 实际 逻辑 ， 不 用 分 心 于 编写 好 看 
的 HTML 和 CSS 代 码 。 


但 是 我 已 经 长 期 关注 应 用 的 后 端 部 分 一 段 时 间 了 。 因此 在 本 章 中 ， 我 暂停 一 下 后 端的 工作 ， 
并 花 点 时 间 向 你 展示 如 何 使 应 用 看 起 来 更 加 优雅 和 专业 。 


本 章 将 与 之 前 的 章节 略 有 不 同 ， 因 为 我 不 会 像 平 常 解说 Python 那样 ， 事 无 巨细 ， 一 一 道 来 ， 
毕竟 Python 才 是 本 教程 的 主要 内 容 。 创建 漂亮 的 网 页 是 一 个 很 广泛 的 话题 ， mA Python Web 
的 后 端 开发 很 大 程度 上 无 关 ， 因 此 我 将 讨论 一 些 基 本 的 指导 方针 和 想法 ， 你 可 以 通过 重新 设 
计 应 用 的 外 观 来 研究 和 学 习 它 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


CSSiE X% 


虽然 我 们 可 以 争辩 说 写 代码 不 容易 ， 但 是 与 那些 必须 让 网 页 在 所 有 Web 浏 览 器 上 具有 良好 一 
致 外 观 的 网 页 设计 师 相 比 ， 我 们 的 痛苦 不 值 一 提 。 虽然 近年 来 这 种 情况 得 到 一 定 程 度 的 缓 
解 ， 但 是 在 一 些 浏 览 器 中 仍然 存在 着 上 汲 的 错误 或 奇怪 的 设 定 ， 这 使 得 设计 网 页 的 任务 变 得 
非常 困难 。 如 果 还 需要 兼容 屏幕 限制 设备 (诸如 平板 电脑 和 智能 手机 ) 的 浏览 器 ， 则 更 加 困 
难 。 

如 果 你 和 我 一 样 ， 只 是 一 个 想 创建 出 规范 网 页 的 开发 人 员 ， 没 有 时 间或 兴趣 去 学 习 底 层 机 制 
a ee 
务 。 通过 这 种 方式 ， 你 会 失去 一 些 创 造 性 的 自由 ， 但 另 一 方面 ， 无 需 通过 太 多 的 功夫 就 可 以 
让 网 nil 览 器 中 看 起 来 都 不 错 。 CSS 框 架 为 普通 类 型 的 用 户 界面 元 素 提 供 了 高 级 CSS 
类 的 集合 ， 其 中 包含 预定 义 样式 。 大 多 数 这 样 的 框架 还 提供 JavaScript 插 件 ， 以 实现 不 能 纯 
粹 使 用 HTML 和 CSS 来 完成 的 功能 。 


Bootstrap 简介 


最 受 欢 迎 的 CSS 框 架 之 一 是 由 Twitter 推出 的 Bootstrap。 如 果 你 想 看 看 这 个 框架 可 以 设计 的 页 
面 类 型 ， 文 档 有 一 些 示例 。 


些 是 使 用 Bootstrap 来 设置 网 页 风格 的 一 些 好 处 : 


© 在 所 有 主流 网 页 浏览 器 中 都 有 相似 的 外 观 


e 自动 处 理 PC 课 面 ， 平 板 电脑 和 手机 屏幕 尺寸 
o 可 定制 的 布局 
® 精心 设计 的 导航 栏 ? 表单 ， 按 钮 ， BE , 弹出 窗 


使 用 Bootstrap 最 直接 的 方法 是 简单 地 在 你 的 基本 模板 中 导入 bootstrap.min.css 文 件 。 可 以 下 
RT DNS A Dia) es eae ae 
Et MACSSR > KECART o 你 可 能 还 需要 导入 包含 框架 JavaScript 代 码 的 
bootstrap.min.js 文 件 ， 以 便 使 用 最 先进 的 功能 。 


幸运 的 是 ， 有 一 个 名 为 Flask-Bootstrap 的 Flask 插 件 ， 它 提供 了 一 个 已 准备 好 的 基础 模板 ， 该 
模板 引入 了 Bootstrap 框 架 。 让 我 们 来 安装 这 个 扩展 : 


(venv) $ pip install flask-bootstrap 


使 用 Flask-Bootstrap 


Flask-Bootstrap 需 要 像 大 多 数 其 他 Flask 插 件 一 样 被 初始 化 : 


app/init.py: Flask-Bootstrap 实 例 。 


# wa, 
from flask_bootstrap import Bootstrap 


app = Flask(__name_) 


# wn. 
bootstrap = Bootstrap(app) 


在 初始 化 插件 之 后 ，bootstrap/base.htm/ 模 板 就 会 变 为 可 用 状态 ， 你 可 以 使 用 extends TAA 
应 用 模板 中 引用 。 


但 是 ， 回 顾 一 下 ， 我 已 经 使 用 了 extends 子 句 来 继承 我 的 基础 模板 ， 这 使 我 可 以 将 页 面 的 公 
共 部 分 放 在 一 个 地 方 。pbase.html 模 板 定义 了 导航 栏 ， 其 中 包含 几 个 链接 ， 并 且 还 导出 了 一 
个 content 块 。 应 用 中 的 所 有 其 他 模板 都 从 基础 模板 继承 ， 并 为 内 容 块 提供 页 面 的 主要 内 


么 我 怎样 才能 适 配 Bootstrap 基 础 模板 呢 ? 解决 方案 是 从 使 用 两 个 层级 到 使 用 三 个 层级 。 
bootstrap/base.html 模 板 提供 页 面 的 基本 结构 ， 其 中 引入 了 Bootstrap 框 架 文件 。 这 个 模板 为 
派生 的 模板 定义 了 一 些 块 ， 例 如 title > navbar 和 content (参见 块 的 完整 列表 ) 。 我 将 
更 改 base.html 模 板 以 从 bootstrap/base.html 派 生 ， 并 提供 title > navbar 和 content 块 的 实 
现 。 反 过 来 ，base.htm/ 将 为 从 其 派生 的 模板 导出 app_content 块 以 定义 页 面 内 容 。 


下 面 你 可 以 看 到 从 Bootstrap 基 础 模板 派生 的 base.html/ 的 代码 。 请 注意 ， 此 列表 不 包含 导航 栏 
的 整个 HTML， 人 得 你 可 以 在 GitHub 上 或 下 载 本 章 的 代码 来 查看 完整 的 实现 。 


app/templates/base.html : 重新 设计 后 的 基础 模板 。 


{% extends 'bootstrap/base.html' %} 


{% block title %} 
{% if title %}{{ title }} - Microblog{% else %}Welcome to Microblog{% endif %} 
{% endblock %} 


{% block navbar %} 
<nav class="navbar navbar -default"> 
. Navigation bar here (see complete code on GitHub) ... 
</nav> 
{% endblock %} 


{% block content %} 
<div class="container"> 

{% with messages = get_flashed_messages() %} 

{% if messages %} 
{% for message in messages %} 
<div class="alert alert-info" role="alert">{{ message }}</div> 
{% endfor %} 

{% endif %} 

{% endwith %} 


{# application content needs to be provided in the app_content block #} 
{% block app_content %}{% endblock %} 
</div> 
{% endblock %} 


从 中 你 可 以 看 到 我 如 何 从 bootstrap/base.html 派 生 此 模板 ， 接 下 来 分 别 实现 了 页 面 标题 、 导 航 
栏 和 页 面 内 容 的 这 三 个 模块 。 


title 块 需要 使 用 <title> 标签 来 定义 用 于 页 面 标题 的 文本 。 对 于 这 个 块 我 简单 地 挪用 了 原 
始 基本 模板 中 <title> HAA SB YH o 


navbar 块 是 一 个 可 选 块 ， 用 于 定义 导航 栏 。 对 于 此 块 ， 我 调整 了 Bootstrap 导 航 栏 文档 中 的 
示例 ， 以 便 它 在 左 侧 展示 网 站 品牌 ， 跟 着 是 Home 和 Explore 的 链接 。 然后 我 添加 了 个 人 主页 
和 登录 或 注销 链接 并 使 其 与 页 面 的 右边 界 对 齐 。 正如 我 上 面 提 到 的 ， 我 在 上 面 的 例子 中 省 略 
了 HTML， 但 是 你 可 以 从 本 章 的 下 载 包 中 获得 完整 的 base.htm/ 模 板 。 


最 后 ， 在 content 块 中 ， 我 定义 了 一 个 顶级 容器 ， 并 在 其 中 1 人 
些 消息 现在 将 显示 为 Bootstrap 警 示 的 样式 。 接 下 来 是 一 个 新 的 app_content 块 ， 这 个 块 用 于 
从 其 派生 的 模板 来 定义 他 们 自己 的 内 容 。 


所 有 页 面 模板 的 原始 版 本 在 名 为 content 的 块 中 定义 了 它们 的 内 容 。 正如 你 在 上 面 看 到 的 ， 
Flask-Bootstrap 使 用 名 为 content 的 块 ， 所 以 我 将 我 的 内 容 块 重 命名 为 app_content 。 所 以 
我 所 有 的 模板 都 必须 重 命名 为 使 用 app_content 作为 它们 的 内 容 块 。 例 如 ， 这 是 404.html 模 
板 的 修改 后 版 本 的 展示 : 


app/templates/404.html : 重新 设计 后 的 404 错 误 模 板 。 


{% extends "base.html" %} 


{% block app_content %} 

<hi>File Not Found</hi> 

<p><a href="{{ url_for('index') }}">Back</a></p> 
{% endblock %} 


iz Bootstrap Š # 


Flask-Bootstrap 在 浑 染 表单 这 方面 做 得 非常 出 色 。 Flask-Bootstrap 不 需要 逐个 设置 表单 字 
段 ， 而 是 使 用 一 个 接受 Flask-WTF 表 单 对 象 作 为 参数 的 宏 ， 并 以 Bootstrap 样 式 泻 染 出 完整 的 
表单 。 


下 面 你 可 以 看 到 重新 设计 后 的 register.html 模 板 : 


app/templates/register.html: : 用 户 注册 模板 。 


{% extends "base.html" %} 
{% import 'bootstrap/wtf.html' as wtf %} 


{% block app_content %} 
<hi>Register</h1> 
<div class="row"> 
<div class="col-md-4"> 
{{ wtf.quick_form(form) }} 
</div> 
</div> 
{% endblock %} 


EREK? 顶端 附近 的 import 语句 与 Python 导入 类 似 。 这 增加 了 一 
个 wtf.quick_form() 宏 ， 它 在 单行 代码 中 泻 染 完 整 的 表单 ， 包 括 对 显示 验证 错误 的 支持 ， 并 
且 适 配 Bootstrap 框 架 的 所 有 样式 。 


再 一 次 地 ， 我 不 会 向 你 展示 我 为 应 用 中 的 其 他 表单 所 做 的 所 有 更 改 ， 但 这 些 更 改 都 是 可 以 在 
GitHub 上 下 载 或 检查 到 的 。 


ia RA PAA 


单条 用 户 动态 的 泻 染 逻辑 被 提取 到 名 为 posthtm/ 的 子 模板 中 。 我 只 需要 在 这 个 模板 上 做 一 些 
很 小 的 调整 ， 就 可 以 使 其 在 Bootstrap 下 看 起 来 很 棒 了 。 


app/templates/_post.html: 重新 设计 后 的 用 户 动态 子 模板 。 


<table class="table table-hover'"> 
<tr> 
<td width="70px"> 
<a href="{{ url_for('user', username=post.author.username) }}"> 
<img src="{{ post.author.avatar(70) }}" /> 
</a> 
</td> 
<td> 
<a href="{{ url_for('user', username=post.author.username) }}"> 
{{ post.author.username }} 
</a> 
says: 
<br> 
{{ post.body }} 
</td> 
</tr> 
</table> 


分 页 链接 是 Bootstrap 提 供 直 接 支 持 的 另 一 个 方面 。 为 此 ， 我 再 一 次 访问 Bootstrap 文档 ， 并 
修改 了 其 中 的 一 个 示例 。 以 下 是 在 index.html 页 面 中 的 分 页 链接 的 代码 : 


app/templates/index.html: 重新 设计 后 的 分 页 链接 。 


<nav aria-label="..."> 
<ul class="pager'"> 
<li class="previous{% if not prev_url %} disabled{% endif %}"> 
<a href="{{ prev_url or '#' }}"> 
<span aria-hidden="true">&larr;</span> Newer posts 
</a> 
</li> 
<li class="next{% if not next_url %} disabled{% endif %}"> 
<a href="{{ next_url or '#' }}"> 
Older posts <span aria-hidden="true">&rarr; </span> 
</a> 
</li> 
</ul> 
</nav> 


请 注意 ， 在 分 页 链接 的 实现 中 ， 当 某 个 方向 没有 更 多 内 容 时 ， 不 是 隐藏 该 链接 ， 而 是 使 用 禁 
用 状态 ， 这 会 使 该 链接 显示 为 灰色 。 


类 似 的 更 改 需 要 应 用 于 user.html， 但 我 不 打算 展示 在 此 处 。 本 章 的 下 载 包 中 包含 这 些 更 改 。 


对 比 


请 下 载 本 章 的 zip 文 件 并 更 新 应 用 。 


下 面 你 可 以 对 照 几 张 美化 前 后 的 图 片 来 观察 转变 情况 。 请 记 住 ， 这 种 转变 是 在 不 改变 一 行 应 
用 逻辑 代码 的 情况 下 实现 的 ! 


T Sign ie - Morobiog 


CO O lecatosso 
Sign in - Micrablog 





é OO @ bcaihost 


Microblog: Howe Explore Login 


Plesse log in to access this page. 


© Picase log in to access this page: 
Sign In Sian | 
ign In 
Usermme Username 
Password 
Password 
Remember Me 
Sn Remember Me 
New User? Click to Register! Signin 
Forget Your Password? Click to Reset Is 
New User? Click to Rogister! 


Forgot Your Password? Click to Reset it 





Mikroblog: Home Explore Profile Logoot Search: 


© Your post is now live! 


Hi, susan! 


Say something 


Svom 
miguel says: 
The sew look of the applicmion is awesome! 


migael says; 
Heo! 


T ome - Microtiog 


© locaho:; 


Your post ia now ivel 


Hi, susan! 


Say something 


Submit 


Miguel says 
The maw lock of the apetication 8 aweaome! 


miguel says: 
Heta! 


Profile 








本 文 翻 译 自 The Flask Mega-Tutorial Part XII: Dates and Times 


这 是 Flask Mega-Tutorial 系 列 的 第 十 二 部 分 ， 我 将 告诉 你 如 何以 适 配 所 有 用 户 的 方式 处 理 日 期 
和 时 间 ， 无 论 他 们 身 处 地 球 上 的 何 处 。 


显示 日 期 和 时 间 是 Microblog 应 用 中 长 期 被 忽略 的 其 中 一 个 方面 。 直 到 现在 ， 我 也 只 是 让 
Python 演 染 了 user 模型 中 的 datetime TR? FAAS ABT post 模型 中 的 datetime 对 


Bo 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


时 区 地 狱 


使 用 服务 器 端的 Python 泻 染 日 期 和 时 间 来 展示 到 用 户 的 浏览 器 并 非 一 个 好 主意 。 考 虑 如 下 的 
例子 ， 我 在 2017 年 9 月 28 日 下 午 4 点 06 分 写 这 篇 文章 。 我 身 处 的 时 区 是 PDT(UTC-7)， 在 
Python 解释 器 中 运行 如 下 : 


>>> from datetime import datetime 
>>> str(datetime.now()) 
"2017-09-28 16:06:30.439388' 

>>> str(datetime.utcnow() ) 
"2017-09-28 23:06:51.406499' 


datetime.now() 调用 返回 我 所 处 位 置 的 本 地 时 间 ， 而 datetime.utcnow() 调用 则 返回 UTC 时 区 
中 的 时 间 。 如 果 我 可 以 让 遍布 世界 不 同 地 区 的 多 人 同时 运行 上 面 的 代码 ， 那 

A datetime.now() 子 数 将 为 他 们 每 个 人 返回 不 同 的 结果 ， 但 是 无 论 位 置 如 

何 ， datetime.utcnow() 总 是 会 返回 同一 时 间 。 那么 你 认为 哪 一 个 更 适合 用 在 一 个 很 可 能 其 用 
户 遍布 世界 各 地 的 Web 应 用 中 呢 ? 


很 明显 ， 服 务 器 必须 管理 一 致 且 独 立 于 位 置 的 时 间 。 如 果 这 个 应 用 增长 到 在 全 世界 不 同 地 区 
都 需要 部 署 生产 服务 器 的 时 候 ， 我 不 希望 每 个 服务 器 都 在 写 入 不 同时 区 的 时 间 惟 到 数据 库 ， 

因为 这 会 导致 其 无 法 正常 地 运行 。 由 于 UTC 是 最 常用 的 统一 时 区 ， 并 且 在 datetime 类 中 也 受 
到 支持 ， 因 此 我 将 会 使 用 它 。 


但 这 种 方法 存在 一 个 严重 问题 。 对 处 于 不 同时 区 的 用 户 ， 如 果 他 们 看 到 的 是 UTC 时 区 中 的 时 
闻 ， 那 么 很 难 确定 是 何 时 发 布 的 信息 。 他 们 需要 事先 知道 展示 的 时 间 是 UTC 时 区 的 ， 才 能 在 
精神 上 调整 自己 的 时 区 。 设想 一 下 PDT 时 区 中 的 一 个 用 户 在 下 午 3 点 发 布 了 一 些 内 容 ， 并 立即 
看 到 该 帖子 以 UTC 时 间 表 示 的 晚上 10:00 或 更 准确 的 22:00， 这 太 混 乱 了 。 


从 服务 器 的 角度 来 说 ， 将 时 间 惟 标准 化 为 UTC， 意 义 重 大 ， 但 这 会 为 用 户 带 来 可 用 性 问题 。 
本 章 的 目标 就 是 解决 该 问题 ， 同 时 保持 服务 器 中 以 UTC 格式 管理 的 所 有 时 间 戳 。 While 
standardizing the timestamps to UTC makes a lot of sense from the servers perspective， 
this creates a usability problem for users. The goal of this chapter is to address this problem 
while keeping all the timestamps managed in the server in UTC. 


时 区 转换 


该 问题 的 直接 解决 方案 是 将 所 有 时 间 惟 从 存储 的 UTC 单位 转换 为 每 个 用 户 的 本 地 时 间 。 这 样 
一 来 ， 服 务 器 可 以 继续 使 用 UTC 来 保持 时 区 的 一 致 性， 而 针对 每 个 用 户 量 身 定 制 的 即时 转换 
来 解决 可 用 性 问题 。 这 个 解决 方案 琼 手 的 部 分 是 要 知道 每 个 用 户 的 位 置 。 


许多 网 站 都 有 一 个 配置 页 面 供用 户 指定 他 们 的 时 区 。 这 将 需要 我 添加 一 个 新 的 页 面 ， 其 中 我 
向 用 户 显示 带 有 时 区 列表 的 下 拉 列 表 。 也 可 能 用 户 在 第 一 次 访问 网 站 时 ， 作 为 注册 的 一 部 
分 ， 会 被 要 求 输入 他 们 的 时 区 。 


虽然 该 方案 可 以 解决 问题 ， 但 要 求 用 户 输入 他 们 已 经 在 其 操作 系统 中 配置 的 信息 有 点 奇怪 。 
如 果 我 能 从 他 们 的 计算 机 中 获取 时 区 设置 ， 似 乎 效率 会 更 高 。 

事实 证 明 ，Web 浏 览 器 可 以 获取 用 户 的 时 区 ， 并 通过 标准 的 日 期 和 时 间 JavaScript APIR E 

Eo 实际 上 有 两 种 方法 来 利用 JavaScript 提 供 的 时 区 信息 : 

。“ 老 派 "方法 是 当 用 户 第 一 次 登录 到 应 用 程序 时 ，Web 浏 览 器 以 某 种 方式 将 时 区 信息 发 送 到 
服务 器 。 这 可 以 通过 Ajax) 调 用 完成 ， 或 者 更 简单 地 使 用 meta refresh tag。 一 旦 服务 器 
知道 了 时 区 ， 就 可 以 将 其 保存 在 用 户 的 会 话 中 ， 或 者 将 其 写 入 用 户 在 数据 库 中 的 条 目 
中 ， 然 后 在 泻 染 模板 时 从 中 调整 所 有 时 间 稚 。 

o “新派 "的 做 法 是 不 改变 服务 器 中 的 东西 ， 而 在 客户 端 中 使 用 JavaScript 来 对 UTC 和 本 地 时 
区 之 间 进 行 转换 。 


两 种 选择 都 是 有 效 的， 但 第 二 种 选择 有 很 大 优势 。 光 是 知道 用 户 的 时 区 并 不 足以 以 用 户 期 望 
的 格式 呈现 日 期 和 时 间 。 浏 览 器 还 可 以 访问 系统 区 域 配置 ， 该 配置 指定 AM/PM 与 24 小 时 制 ， 
DD/MM/YYYY 与 MM/DD/YYYY， 以 及 许多 其 他 文化 或 地 区 风格 之 类 的 东西 。 


如 果 这 还 不 够 ， 新 派 方法 还 有 另 一 个 优势 ， 用 一 个 开源 的 库 来 完成 所 有 这 些 工作 | 


Moment.js 和 Flask-Moment 简 介 


Moment.js 是 一 个 小 型 的 JavaScript 开 源 库 ， 它 将 日 期 和 时 间 转 换 成 目前 可 以 想象 到 的 所 有 格 
式 。 不 久 前 ， 我 创建 了 Flask-Moment， 一 个 小 型 Flask 播 件 ， 它 可 以 使 你 在 应 用 中 轻松 使 用 
moment.js。 


因此 ， 让 我 们 从 安装 Flask-Moment 来 开始 吧 : 


(venv) $ pip install flask-moment 


使 用 常规 方法 添加 该 插件 到 Flask 应 用 中 : 


app/__init__.py : Flask-Moment 实 例 。 


# ,，,， 
from flask_moment import Moment 


app = Flask(__name_ ) 
# 


moment = Moment(app) 


与 其 他 播 件 不 同 的 是 ，Flask-Moment 与 momentjs 一 起 工作 ， 因 此 应 用 的 所 有 模板 都 必须 包 
含 moment.js。 为 了 确保 该 库 始 终 可 用 ， 我 将 把 它 添加 到 基础 模板 中 ， 可 以 通过 两 种 方式 完 
成 。 最 直接 的 方法 是 显 式 添加 一 个 <script> 标签 来 引入 库 ， 但 Flask-Moment 

的 moment.include_moment() HRY VA 更 容易 地 实现 它 ? 它 直 接生 成 了 一 个 <script> 标签 并 在 
其 中 包含 moment.js : 


app/templates/base.html : 在 基础 模板 中 包含 moment.js 


{% block scripts %} 
{{ super() }} 


{{ moment.include_moment() }} 
{% endblock %} 


我 在 这 里 添加 的 scripts 块 是 Flask-Bootstrap 基 础 模板 暴露 的 另 一 个 块 ， 这 是 JavaScript 引 A 
的 地 方 。 该 块 与 之 前 的 块 不 同 的 地 方 在 于 它 已 经 在 基础 模板 中 定义 了 一 些 内容 了 。 我 想 要 追 
加 moment.js 库 的 话 ， 就 需要 使 用 super() 语句 ， 才 能 继承 基础 模板 中 已 有 的 内 容 ， 否 则 就 是 
替换 。 


使 用 Moment.js 


Moment.js 为 浏 览 器 提供 了 一 个 moment 类 。 呈现 时 间 惟 的 第 一 步 是 创建 此 类 的 对 象 ， 并 以 
ISO 8601 格 式 传递 所 需 的 时 间 惟 。 这 里 是 一 个 例子 : 


t = moment ('2017-09-28T21:45:23Z') 


如 果 你 对 日 期 和 时 间 不 熟悉 ISO 8601 标 准 格式 ， 格 式 如 

Fi {{ year }}-{{ month }}-{{ day }}T{{ hour }}:{{ minute }}:{{ second }}{{ timezone }} 

。 我 已 经 决定 我 只 使 用 UTC 时 区 ， 因 此 最 后 一 部 分 总 是 将 会 是 z ， 它 表示 ISO 8601 标 准 中 的 
UTC ° 


moment SRA AK His MI T LAA IE o 以 下 是 一 些 最 常见 的 几 种 : 


moment ('2017-09-28T21:45:23Z').format('L') 
"09/28/2017" 

moment ( '2017-09-28T21:45:23Z').format('LL') 
"September 28, 2017" 

moment ( '2017-09-28T21:45:23Z').format('LLL') 
"September 28, 2017 2:45 PM" 

moment ( '2017-09-28T21:45:23Z').format('LLLL') 
"Thursday, September 28, 2017 2:45 PM" 

moment ( '2017 -09-28T21:45:23Z').format('dddd') 
"Thursday" 

moment ( '2017-09-28T21:45:23Z' ).fromNow( ) 

"7 hours ago" 

moment ( '2017-09-28T21:45:23Z').calendar() 
"Today at 2:45 PM" 


此 示例 创建 了 一 个 moment 对 象 ， 该 对 象 被 初始 化 为 2017 年 9 月 28 日 晚上 9:45 UTC > 你 可 以 
看 到 ， 我 上 面 党 试 的 所 有 选项 都 以 UTC-7 时 区 来 呈现 ， 因 为 这 是 我 计算 机 上 配置 的 时 区 。 你 
可 以 在 microblog 上 进行 此 操作 ， 只 要 你 引入 了 moment.js。 或 者 你 也 可 以 

在 https:/momentjs.com/ 上 尝试 。 


请 注意 不 同 的 方法 是 如 何 创建 的 不 同 的 表示 。 使 用 format() ， 你 可 以 控制 字符 串 的 输出 格 
式 ， 类 似 于 Python 中 的 strftime 吨 数 。 fromNow() 和 calendar() 方法 很 有 趣 ， 因 为 它们 会 根 
据 当 前 时 间 显示 时 间 稚 ， 因 此 你 可 以 获得 诸如 一 分 钟 前 "或 "两 小 时 内 "等 输出 。 


如 果 你 直接 在 JavaScript 中 运行 ， 则 上 述 调 用 将 返回 泻 染 后 的 时 间 惟 字符 串 。 然后 ， 你 可 以 
将 此 文本 插入 页 面 上 的 适当 位 置 ， 不 幸 的 是 ， 这 需要 JavaScript 与 DOM 配 合 使 用 。 Flask- 
Moment 插 件 通 过 局 用 一 个 类 似 于 JavaScript 上 的 moment 对 象 ， 大 大 简化 了 对 moment.js 的 使 
用 ， 并 融合 了 所 需 的 JavaScript 逮 辑 ， 使 泻 染 后 的 时 间 展 示 在 页 面 上 。 


我 们 来 看 看 出 现在 个 人 主页 中 的 时 间 稚 。 当前 的 Userhtm/ 模 板 使 用 Python 生成 时 间 的 字符 串 
表示 。 现在 我 可 以 使 用 Flask-Moment 泻 染 此 时 间 惟 ， 如 下 所 示 : 


app/templates/user.html: 使 用 moment.js 泻 当时 间 稚 。 


{% if user.last_seen %} 
<p>Last seen on: {{ moment(user.last_seen).format('LLL') }}</p> 
{% endif %} 


如 你 所 见 ，Flask-Moment 使 用 的 语法 类 似 于 JavaScript 库 的 语法 ， 其 中 一 个 区 别 

Æ’ moment() 的 参数 现在 是 Python 的 datetime 对 象 ， 而 不 是 ISO 8601 字 符 串 。 从 模板 发 出 
的 moment() 调用 也 会 自动 生成 所 需 的 JavaScript 代 码 ， 以 将 呈现 的 时 间 惟 插入 DOM 的 适当 位 
置 。 


我 可 以 利用 Flask-Moment 和 moment.js 的 第 二 个 地 方 是 被 主页 和 个 人 主页 调用 的 _posthtm/ 子 
模板 。 在 该 模板 的 当前 版 本 中 ， 每 条 用 户 动态 都 以 “用 户 名 说 : " 行 开头 。 现 在 我 可 以 添加 一 
个 用 fromNow() XÈ 389 BY lal RR : 


app/templates/_post.html: 7 M P a AFAR P iz HAT MA] BK o 


<a href="{{ url_for('user', username=post.author.username) }}"> 
{{ post.author.username }} 

</a> 

said {{ moment(post.timestamp).fromNow() }}: 

<br> 

{{ post.body }} 


Th’ RTRA Bl RAAN ARA Flask-Moment##momentjs4 i RF > KM te ty : 
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本 文 翻 译 自 The Flask Mega-Tutorial Part XIII: 118n and L10n 


这 是 Flask Mega-Tutorial 系 列 的 第 十 三 部 分 ， 我 将 告诉 你 如 何 扩 展 Microblog 应 用 以 支持 多 种 
语言 。 作 为 其 中 的 一 部 分 ， 你 还 将 学 习 如 何 为 flask 命 令 创 建 自己 的 CLI 扩 展 。 


本 章 的 主题 是 国际 化 和 本 地 化 ， 通 常 缩写 为 118n 和 L10n。 为 了 使 我 的 应 用 对 不 会 英语 的 人 更 
加 友好 ， 我 将 在 语言 翻译 机 制 的 帮助 下 ， 实 施 翻 译 工作 流程 ， 来 使 用 多 种 语言 向 用 户 提供 服 


务 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


CE 
Flask-Babel fj 4^ 
你 猜 对 了 ，Flask-Babel 正 是 用 于 简化 翻译 工作 的 。 可 以 使 用 pip 命 令 安装 它 : 


(venv) $ pip install flask-babel 


Flask-Babel 的 初始 化 与 之 前 的 插件 类 似 : 
app/__init__.py : Flask-Babel 实 例 。 


# ,,， 

from flask_babel import Babel 
app = Flask(__name_) 

# 


babel = Babel(app) 


作为 本 章 的 一 部 分 ， 我 将 向 你 展示 如 何 将 应 用 翻译 成 西班牙 语 ， 因 为 我 碰巧 会 这 种 语言 。 我 
当然 也 可 以 与 翻译 机 制 合作 来 支持 其 他 语言 。 为 了 跟踪 支持 的 语言 列表 ， 我 将 添加 一 个 配置 
变量 : 


config.py : 支持 的 语言 列表 。 


class Config(object): 
ee 
LANGUAGES = ['en', 'es'] 


我 为 本 应 用 使 用 双 字 母 代 码 来 表示 语言 种 类 ， 但 如 果 你 需要 更 具体 ， 还 可 以 添加 国家 代码 。 
例如 ， 你 可 以 使 用 en-us ， en-GB 和 en-cA 来 支持 美国 S 英国 和 加 拿 大 的 英语 以 示 区 分 p 


Babel 实例 提供 了 一 个 localeselector 装饰 器 。 为 每 个 请 求 调用 装饰 器 函数 以 选择 用 于 该 请 
求 的 语言 : 


app/__init__.py : 选择 最 匹配 的 语言 。 


from flask import request 
# ow. 


@babel.localeselector 
def get_locale(): 
return request.accept_languages.best_match(app.config['LANGUAGES' ] ) 


这 里 我 使 用 了 Flask 中 request 对 象 的 属性 accept_languages ° request 对 象 提供 了 一 个 高 级 
接口 ， 用 于 处 理 客户 端 发 送 的 带 Accept-Language 头 部 的 请 求 。 该 头 部 指定 了 客户 端 语言 和 

区 域 设 置 首 选项 。 该 头 部 的 内 容 可 以 在 浏览 器 的 首选 项 页 面 中 配置 ， 默 认 情 况 下 通常 从 计算 

机 操作 系统 的 语言 设置 中 导入 。 大 多 数 人 其 至 不 知道 存在 这 样 的 设置 ， 但 是 这 是 有 用 的 ， 

为 应 用 可 以 根据 每 个 语言 的 权重 ， 提 供 优选 语言 的 列表 。 为 了 满足 你 的 好 奇 心 ， 下 面 是 一 个 

复杂 的 Accept-Languages 头 部 的 例子 : 


Accept-Language: da, en-gb;q=0.8, en;q=0.7 


这 表示 丹麦 语 ( da ) 是 首选 语言 (默认 权重 = 1.0) ， 其 次 是 英 式 英语 ( en- ) ， 其 权重 
为 0.8， 最 后 是 通用 英语 (en) ， 权 重 为 0.7。 


要 选择 最 佳 语言 ， 你 需要 将 客户 请 求 的 语言 列表 与 应 用 支持 的 语言 进行 比较 ， 并 使 用 客户 端 
提供 的 权重 ， 查 找 最 佳 语言 。 这 样 做 的 逻辑 有 点 复杂 ， 但 它 已 经 全 部 封装 在 best_match() 方 
法 中 了 ， 该 方法 将 应 用 提供 的 语言 列表 作为 参数 并 返回 最 佳 选择 。 


标记 文本 以 在 Python 源 代 码 中 执行 翻译 


好 吧 ， 坏 消息 来 了 。 支持 多 语言 的 常规 流程 是 在 源 代码 中 标记 所 有 需要 翻译 的 文本 。 文本 标 
记 后 ，Flask-Babel 将 扫描 所 有 文件 ， 并 使 用 gettext 工 具 将 这 些 文本 提取 到 单独 的 翻译 文件 
Po 不 幸 的 是 ， 这 是 一 个 繁琐 的 任务 ， 并 且 是 启用 翻译 的 必要 条 件 。 

我 将 在 这 里 向 你 展示 标记 操作 的 几 个 示例 ， 你 也 可 以 从 下 载 包 获取 本 章 完 整 的 更 改 集 ， 当 

然 ， 也 可 以 直接 查看 GitHub 的 页 面 。 


为 翻译 而 标记 文本 的 方式 是 将 它们 封装 在 一 个 函数 调用 中 ， 该 子 数 调用 为 _() ， 仅 仅 是 一 个 
下 划 线 。 最 简单 的 情况 是 源 代 码 中 出 现 的 字符 串 。 下 面 是 一 个 flask() 语句 的 例子 : 
from flask_babel import _ 


# wn, 
flash(_('Your post is now live!')) 


O 函数 用 于 原始 语言 文本 (在 这 种 情况 下 是 英文 ) 的 封装 。 该 函数 将 使 用 
由 localeselector 装饰 器 装饰 的 选择 函数 ， 来 为 给 定 客 户 端 查找 正确 的 翻译 语言 。 _() 函数 
随后 返回 翻译 后 的 文本 ， 在 本 处 ， 翻 译 后 的 文本 将 成 为 flash) 的 参数 。 


但 是 不 可 能 每 个 情况 都 这 么 简单 ， 试 想 如 下 的 另 一 个 flash() 调用 : 


flash('User {} not found.'.format(username) ) 


该 文本 具有 一 个 安插 在 静态 文本 中 间 的 动态 组 件 。 O 函数 的 语法 支持 这 种 类 型 的 文 二， 但 
ERT OMA EE EBRD : 


flash(_('User %(username)s not found.', username=username) ) 


还 有 更 难处 理 的 情况 。 有 些 字符 串 文字 并 非 是 在 发 生 请 求 时 分 配 的 ， 比 如 在 应 用 启动 时 。 
此 在 评估 这 些 文本 时 ， 无 法 知道 要 使 用 哪 种 语言 。 一 个 例子 是 与 表单 字段 相关 的 标签 ， 处 理 
这 些 文本 的 唯一 解决 方案 是 找到 一 种 方法 来 延迟 对 字符 串 的 评估 ， 直 到 它 被 使 用 ， 比 如 有 实 
际 上 的 请 求 发 生 了 。 Flask-Babel 提 供 了 一 个 称 为 lazy_gettext() 的 _() 函数 的 延迟 评估 的 
版 本 : 


from flask_babel import lazy_gettext as _l 


class LoginForm(FlaskForm) : 
username = StringField(_1l('Username'), validators=[DataRequired()]) 
Haa 


在 这 里 ， 我 正在 导入 的 这 个 翻译 函数 被 重 命名 为 10 ， 以 使 其 看 起 来 与 原始 的 _() 相似 。 
这 个 新 函数 将 文本 包装 在 一 个 特殊 的 对 象 中 ， 这 个 对 象 会 在 稍 后 的 字符 串 使 用 时 触发 翻译 。 


Flask-Login 插 件 只 要 将 用 户 重 定向 到 登录 页 面 ， 就 会 闪现 消息 。 此 消息 为 英文 ， 来 自 插件 本 
身 。 为 了 确保 这 个 消息 也 能 被 翻译 ， 我 将 重 写 默认 消息 ， 并 用 _1() 函数 进行 延迟 处 理 : 


login = LoginManager (app) 
login.login_view = 'login' 
login.login_message = _1('Please log in to access this page.') 


ar A = x ab 4 一 Ê. ` 
标记 文本 以 在 模板 中 进行 翻译 
在 前 面 的 章节 中 ， 你 已 经 看 到 了 如 何在 Python 源 代码 中 标记 可 翻译 的 文本 ， 但 这 只 是 该 过 程 
的 一 部 分 ， 因 为 模板 文件 也 包含 文本 。 O 函数 也 可 以 在 模板 中 使 用 ， 所 以 过 程 非常 相似 。 
例如 ， 参 考 来 自 404.htm/ 的 这 段 HTML 代 码 : 

<hi>File Not Found</h1i> 
启用 翻译 之 后 的 版 本 是 : 


<hi>{{ _('File Not Found') }}</h1> 


请 注意 ， 除 了 用 _() 包装 文本 外 ， 还 需要 添加 {{...}} 来 强制 _() 进行 翻译 ， 而 不 是 将 其 视 
为 模板 中 的 文本 字面 量 。 


对 于 具有 动态 组 件 的 更 复杂 的 短语 ， 也 可 以 使 用 参数 : 


<hi>{{ _('Hi, %(username)s!', username=current_user.username) }}</h1> 


_post.html P t — N44 5] RR 99 RIE RIE T — He HY A) A IM: 


{% set user_link %} 
<a href="{{ url_for('user', username=post.author.username) }}"> 
{{ post.author.username }} 
</a> 
{% endset %} 
{{ _('%(username)s said %(when)s', 
username=user_link, when=moment(post.timestamp).fromNow()) }} 


这 里 的 问题 是 我 希望 username 是 一 个 超 链接 ， 指 向 用 户 的 个 人 主页 ， 而 不 仅仅 是 名 字 ， 所 以 
我 必须 使 用 set 和 endset 模板 指令 创建 一 个 名 为 user_link 的 中 间 变 量 ， 然 后 将 其 作为 参 
数 传递 给 翻译 函数 。 


正如 我 上 面 提 到 的 ， 你 可 以 下 载 该 版 本 的 应 用 ， 其 中 的 Python 源 代 码 和 模板 中 都 已 被 标记 成 
可 翻译 文本 。 


提取 文本 进行 翻译 


一 旦 应 用 所 有 O 和 _1() 都 到 位 了 ， 你 可 以 使 用 pybabel 命令 将 它们 提取 到 一 个 .pot 文 件 
中 ， 该 文件 代表 可 移植 对 象 模板 。 这 是 一 个 文本 文件 ， 其 中 包含 所 有 标记 为 需要 翻译 的 文 
本 。 这 个 文件 的 目的 是 作为 一 个 模板 来 为 每 种 语言 Peres o 


提取 过 程 需要 一 个 小 型 配置 文件 ， 告 诉 pybabel 哪 些 文件 应 该 被 扫描 以 获得 可 翻译 的 文本 。 下 
面 你 可 以 看 到 我 为 这 个 应 用 创建 的 babel.cfg : 


babel.cfg : PyBabel 配 置 文件 。 


[python: app/**.py] 
[jinja2: app/templates/**.htmll] 
extensions=jinja2.ext.autoescape, jinja2.ext.with_ 


前 两 行 分 别 定义 了 Python 和 Jinja2 模 板 文 件 的 文件 名 匹配 模式 。 第 三 行 定义 了 Jinja2 模 板 引 擎 
提供 的 两 个 扩展 ， 以 帮助 Flask-Babel 正 确 解 析 模 板 文件 。 


可 以 使 用 以 下 命令 来 将 所 有 文本 提取 到 pot 文件: 


(venv) $ pybabel extract -F babel.cfg -k _1 -o messages.pot . 


pybabel extract 命令 读 取 -F 选项 中 给 出 的 配置 文件 ， 然 后 从 命令 给 出 的 目录 (当前 目录 或 
本 处 的 ，) 扫描 与 配置 的 源 匹配 的 目录 中 的 所 有 代码 和 模板 文件 。 默认 情况 

下 ， pybabel 将 查找 O 以 作为 文本 标记 ， 但 我 也 使 用 了 重 命名 为 1() 的 延迟 版 本 ， 所 以 
我 需要 用 -k _1 来 告诉 该 工具 也 要 查找 它 。 -o 选项 提供 输出 文件 的 名 称 。 


我 应 该 注意 ，messages.pot 文 件 不 需要 合并 到 项 目 中 。 这 是 一 个 只 要 再 次 运行 上 面 的 命令 ， 
就 可 以 在 需要 时 轻松 地 重新 生成 的 文件 。 因 此 ， 不 需要 将 该 文件 提交 到 源 代码 管理 。 


生成 语言 目录 


该 过 程 的 下 一 步 是 在 除了 原始 语言 (在 本 例 中 为 英语 ) 之 外 ， 为 每 种 语言 创建 一 份 翻译 。 我 
要 从 添加 西班牙 语 (语言 代码 es ) 开始 ， 所 以 这 样 做 的 命令 是 : 


(venv) $ pybabel init -i messages.pot -d app/translations - es 
creating catalog app/translations/es/LC_MESSAGES/messages.po based on messages.pot 


pybabel init 命令 将 messages.pot 文 件 作 为 输入 ， 并 将 语言 目录 写 入 -d 选项 中 指定 的 目录 
Po -1 选项 中 指定 的 是 翻译 语言 。 我 将 在 app/translations 目 录 中 安装 所 有 翻译 ， 因 为 这 是 
Flask-Babel 默 认 提 取 翻 译文 件 的 地 方 。 该 命令 将 在 该 目录 内 为 西班牙 数据 文件 创建 一 个 es 子 
目录 。 特别 是 ， 将 会 有 一 个 名 为 app/translations/es/LC_MESSAGES/messages.po 的 新 文 
件 ， 是 需要 翻译 的 文件 路 径 。 


如 果 你 想 支持 其 他 语言 ， 只 需要 各 自 的 语言 代码 重复 上 述 命令 ， 就 能 使 得 每 种 语言 都 有 一 个 
包含 messages.po 文 件 的 存储 库 。 


在 每 个 语言 存储 库 中 创建 的 messages.po 文件 使 用 的 格式 是 语言 翻译 的 事实 标准 ， 使 用 的 格式 
为 gettext。 以 下 是 西班牙 语 messages.po 开 头 的 若干 行 : 


# Spanish translations for PROJECT. 

# Copyright (C) 2017 ORGANIZATION 

# This file is distributed under the same license as the PROJECT project. 
# FIRST AUTHOR <EMAIL@ADDRESS>, 2017. 

# 

msgid nn 

msgstr "" 

"Project-Id-Version: PROJECT VERSION\n" 
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" 
"POT-Creation-Date: 2017-09-29 23:23-0700\n" 
"PO-Revision-Date: 2017-09-29 23:25-0700\n" 
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" 
"Language: es\n" 

"Language-Team: es <LL@li.org>\n" 
"Plural-Forms: nplurals=2; plural=(n != 1)\n" 
"MIME-Version: 1.0\n" 

"Content-Type: text/plain; charset=utf-8\n" 
"Content-Transfer-Encoding: 8bit\n" 
"Generated-By: Babel 2.5.1\n" 


#: app/email.py:21 
msgid "[Microblog] Reset Your Password" 
msgstr "" 


#: app/forms.py:12 app/forms.py:19 app/forms.py:50 
msgid "Username" 
msgstr "" 


#: app/forms.py:13 app/forms.py:21 app/forms.py:43 
msgid "Password" 
msgstr "" 


如 果 你 跳 过 首 段 ， 可 以 看 到 后 面 的 是 从 O 和 _1() 调用 中 提取 的 字符 串 列 表 。 对 每 个 文 

本 ， 都 会 展示 其 人 ee 然后 msgid 行 包含 原始 语言 的 文本 ， 

的 msgstr 行 包含 一 个 空 字符 事 。 这 些 空 字符 串 需 要 被 编辑 ， 以 使 目标 语言 中 的 文本 内 容 被 卉 
充 。 


a .po 文件 一 起 工作 。 如 果 你 擅长 编辑 文本 文件 ， 量 少 的 时 候 也 就 黑 
， 但 如 果 你 正在 处 理 大 型 项 目 ， 可 能 会 推荐 使 用 专门 的 编辑 器 。 最 流行 的 翻译 应 用 程序 是 
的 poedit， 可 用 于 所 有 主流 操作 系统 。 如 果 你 熟悉 vim， 那 么 po.vim 插件 会 提供 一 些 键 值 
映射 ， 使 得 处 理 这 些 文件 更 加 轻松 。 


在 添加 翻译 后 ， 你 可 以 在 下 面 看 到 一 部 分 西班牙 语 messages.po : 


#: app/email.py:21 
msgid "[Microblog] Reset Your Password" 
msgstr "[Microblog] Nueva Contraseña" 


#: app/forms.py:12 app/forms.py:19 app/forms.py:50 
msgid "Username" 
msgstr "Nombre de usuario" 


#: app/forms.py:13 app/forms.py:21 app/forms.py:43 


msgid "Password" 
msgstr "Contraseña" 


本 章 的 下 载 包 中 包含 所 有 翻译 ， 此 文件 当然 也 在 其 中 ， 所 以 你 不 必 担 心 这 部 分 的 翻译 工作 。 


1messages.Do 文 件 是 一 种 用 于 翻译 的 源 文件 。 当 你 想 开始 使 用 这 些 翻 译 后 的 文本 时 ， 这 个 文 
件 需 要 被 编译 成 一 种 格式 ， 这 种 格式 在 运行 时 可 以 被 应 用 程序 使 用 。 要 编译 应 用 程序 的 所 有 
翻译 ， 可 以 使 用 pybabel compile 命令 ， 如 下 所 示 : 

(venv) $ pybabel compile -d app/translations 


compiling catalog app/translations/es/LC_MESSAGES/messages.po to 
app/translations/es/LC_MESSAGES/messages.mo 


BARE 2 EE S FF ik EP HY) messages.poF ù *messages.moxX 4 > .Imo 文 件 是 Flask- 
Babel 将 用 于 为 应 用 程序 加 载 翻译 的 文件 。 


在 为 西班牙 语 或 任何 其 他 添加 到 项 目 中 的 语言 创建 messages.mo 文 件 之 后 ， 可 以 在 应 用 中 使 
用 这 些 语言 。 如 果 你 想 查看 应 用 程序 以 西班牙 语 显示 的 方式 ， 则 可 以 在 Web 浏 览 器 中 编辑 语 
言 配置 ， 以 将 西班牙 语 作为 首选 语言 。 对 Chrome， 这 是 设置 页 面 的 高 级 部 分 : 
Languages 
Language 
Onder languages based on your preference 
Spanish 
English (United States) 
English 


Add languages 


Offer to translate pages that arent in a language you read E) 
如 果 你 不 想 更 改 浏 览 器 设置 ， 另 一 种 方法 是 通过 使 localeselector 函数 始终 返回 一 种 语言 来 


强制 实现 。 对 西班牙 语 ， 你 可 以 这 样 做 : 
app/__init__.py : 选择 最 佳 语 言 。 


@babel.localeselector 

def get_locale(): 
# return request.accept_languages.best_match(app.config[ 'LANGUAGES' ] ) 
return 'es' 


使 用 为 西班牙 语 配置 的 浏览 器 运行 该 应 用 或 返回 es 的 localeselector 函数 ， 将 使 所 有 文本 
在 使 用 该 应 用 时 显示 为 西班牙 文 。 


更 新 翻译 


处 理 翻 译 时 的 一 个 常见 情况 是 ， 即 使 翻译 文件 不 完整 ， 你 也 可 能 要 开始 使 用 翻译 文件 。 这 是 
非常 好 的 ， 你 可 以 编译 一 个 不 完整 的 /messages.Do 文 件 ， 任 何 可 用 的 翻译 都 将 被 使 用 ， 而 任 
何 缺 失 的 部 分 将 使 用 原始 语言 。 随 后， 你 可 以 继续 处 理 翻译 并 再 次 编译 ， 以 便 在 取得 进展 时 


更 新 messages.mo 文 件 。 


如 果 在 添加 _() 包装 器 时 错过 了 一 些 文本 ， 则 会 出 现 另 一 种 常见 情况 。 在 这 种 情况 下 ， 你 会 
发 现 你 错过 的 那些 文本 将 保持 为 英文 ， 因 为 Flask-Babel 对 他 们 一 无 所 知 。 当 你 检测 到 这 种 情 
况 时 ， 会 想 要 将 其 用 () 或 1() 包装 ， 然 后 执行 更 新 过 程 ， 这 包括 两 个 步骤 : 


(venv) $ pybabel extract -f babel.cfg -k _1 -o messages.pot . 
(venv) $ pybabel update -i messages.pot -d app/translations 


extract 命令 与 我 之 前 执行 的 命令 相同 ， 但 现在 它 会 生成 Inessages.pot 的 新 版 本 ， 其 中 包含 
所 有 以 前 的 文本 以 及 最 近 用 O 或 _1() 包装 的 文本 。 update 调用 采用 新 

的 messages.pot 文件 并 将 其 合并 到 与 项 目 相 关 的 所 有 messages.po 文 件 中 。 这 将 是 一 个 智能 
合并 ， 其 中 任何 现 有 的 文本 将 被 单独 保留 ， 而 只 有 在 messages.pot 中 添加 或 删除 的 条 目 才 会 


受到 影响 。 


messages.po 文 件 更 新 后 ， 你 就 可 以 继续 新 的 测试 了 ， 再 次 编译 它 ， 以 便 对 应 用 生效 。 


翻译 日 期 和 时 间 


现在 ， 我 已 经 为 Python 代码 和 模板 中 的 所 有 文本 提供 了 完整 的 西班牙 语 翻译 ， 但 是 如 果 你 使 
用 西班牙 语 运行 应 用 并 且 是 一 个 很 好 的 观察 者 ， 那 么 会 注意 到 还 有 一 些 内容 以 英文 显示 。 我 
间 的 是 由 Flask-Moment 和 moment.js 生 成 的 时 间 改 ， 显 然 这 些 时 间 和 戳 并 未 包含 在 翻译 工作 

中 ， 因 为 这 些 包 生成 的 文本 都 不 是 应 用 程序 源 代码 或 模板 的 一 部 分 。 


moment.js 库 确实 支持 本 地 化 和 国际 化 ， 所 以 我 需要 做 的 就 是 配置 适当 的 语言 。Flask-Babel 
通过 get_locale() 函数 返回 给 定 请 求 的 语言 和 语言 环境 d 所 以 我 要 做 的 就 是 将 语言 环境 添加 
到 g 对 象 ， 以 便 我 可 以 从 基础 模板 中 访问 它 : 


app/routes.py : 存储 选择 的 语言 到 flask.g 中 。 


# ,,， 
from flask import g 
from flask_babel import get_locale 


# ,,， 
@app.before_request 
def before_request(): 


# i... 
g.locale = str(get_locale()) 


Flask-Babel#) get_locale() 函数 返回 一 个 本 地 语言 对 象 ， 但 我 只 想 获得 语言 代码 ， 可 以 通过 
将 该 对 象 转换 为 字符 串 来 获取 语言 代码 。 现 在 我 有 了 g.locale ， 可 以 从 基础 模板 中 访问 它 ， 
并 以 正确 的 语言 配置 moment.js : 


app/templates/base.html : 为 moment.js 设 置 本 地 语言 


{% block scripts %} 
{{ super() }} 
{{ moment.include_moment() }} 
{{ moment.lang(g.locale) }} 
{% endblock %} 


现在 所 有 的 日 期 和 时 间 都 与 文本 使 用 相同 的 语言 了 。 你 可 以 在 下 面 看 到 西班牙 语 的 外 观 : 





Microblog iniclo Explor Pert! Salr 


iHola, miguel! 


miguel dja hace § dias 
The raw lock of the application is awesome 


此 时 ， 除 用 户 在 用 户 动态 或 个 人 资料 说 明 中 提供 的 文本 外 ， 所 有 其 他 的 文本 均 可 翻译 成 其 他 


你 可 能 会 同意 我 的 看 法 ， page 令 有 点 长 ， 难 以 记忆 。 我 将 利用 这 个 机 会 向 你 展示 如 何 创 
建 与 flask 命令 集成 的 自 定 义 命 令 。 到 目前 为 止 ， 你 已 经 看 到 我 使 用 Flask-Migrate 扩 展 提供 
的 flask run 、 flask shell iA flask db 子 命令 。 将 应 用 特定 的 命令 添加 到 flask 实际 
上 也 很 容易 。 所 以 我 现在 要 做 的 就 是 创建 一 些 简单 的 命令 ， 并 用 这 个 应 用 特有 的 参数 触 

发 pybabel f 命令 。 我 要 添加 的 命令 是 : 


e flask translate init LANG 用 于 添加 新 语言 
e flask translate update 用 于 更 新 所 有 语言 存储 库 
e flask translate compile 用 于 编译 所 有 语言 存储 库 


babel export 步骤 不 会 设置 为 一 个 命令 ， 因 为 生成 messages.potl 文 件 始 终 
行 init 或 update 命令 的 先决 条 件 ， 因 此 这 En 时 文 
件 。 


Flask 依 赖 Click 进 行 所 有 命令 行 操作 。 像 translate 这 样 的 命令 是 几 个 子 命令 的 根 ， 它 们 是 通 
过 app.cli.group() 装饰 器 创 建 的 。 我 将 把 这 些 命令 放 在 一 个 名 为 gapp/cli.jpy 的 新 模块 中 : 


app/cli.py : 翻译 命令 组 


from app import app 


@app.cli.group() 

def translate(): 
"""Translation and localization commands.""" 
pass 


该 命令 的 名 称 来 自 被 装饰 函数 的 名 称 ， 并 且 帮 助 消息 来 自 文档 字符 串 。 由 于 这 是 一 个 父 命 
令 ， 它 的 存在 只 为 子 命令 提供 基础 ， 函 数 本 身 不 需要 执行 任何 操作 。 


update 和 compile 很 容易 实现 ， 因 为 它们 没有 任何 参数 : 


app/cli.py : 更 新 子 命令 和 编译 子 命令 : 


import os 
# wa. 


@translate.command() 
def update(): 
"""Update all languages.""" 
if os.system('pybabel extract -F babel.cfg -k _1 -o messages.pot .'): 
raise RuntimeError('extract command failed') 
if os.system('pybabel update -i messages.pot -d app/translations'): 
raise RuntimeError('update command failed' ) 
os.remove('messages.pot' ) 


@translate.command() 
def compile(): 
"""Compile all languages.""" 
if os.system('pybabel compile -d app/translations'): 
raise RuntimeError('compile command failed' ) 


请 注意 ， 这 些 函 数 的 装饰 器 是 如 何 从 translate 父 函 数 派 生 的 。 这 似乎 令 人 困惑 ， 
为 translate() 是 一 个 函数 ， 但 它 是 Click 构 建 命令 组 的 标准 方式 。 与 translate() 函数 相 
同 ， 这 些 函 数 的 文档 字符 串 在 --help 输出 中 用 作 帮 助 消息 。 


你 可 以 看 到 ， 对 于 所 有 命令 ， 运 行 它们 并 确保 返回 值 为 替 (这 意味 着 命令 没有 返回 任何 错 

ik ) 由 如 果 命 令 错 误 ， 那么 我 会 引发 一 个 RuntimeError ? 这 会 导致 脚本 停止 。 update() Ba 
数 在 同 一 个 命令 中 结合 了 extract 和 update WY 步骤 ， 如 果 一 切 都 成 功 的 话 > 它 会 在 更 新 完成 后 
删除 messages.pot 文 件 ， 因 为 当 再 次 需要 这 个 文件 时 ， 可 以 很 容易 地 重新 生成 。 


init 命令 将 新 的 语言 代码 作为 参数 。 这 是 其 执行 流程 : 


app/cli.py : Init 子 命 


import click 


@translate.command() 
@click.argument('lang' ) 
def init(lang): 
"""Tnitialize a new language.""" 
if os.system('pybabel extract -F babel.cfg -k _1 -o messages.pot .'): 
raise RuntimeError('extract command failed' ) 
if os.system( 
"pybabel init -i messages.pot -d app/translations -1 ' + lang): 
raise RuntimeError('init command failed') 
os.remove('messages.pot' ) 


该 命令 使 用 @click.argument 装饰 器 来 定义 语言 代码 8 Click 将 命令 中 提供 的 值 作 为 参数 传递 
给 处 理 函 数 ， 然 后 将 该 参数 并 入 到 init 命令 中 。 

启用 这 些 命令 的 最 后 一 步 是 导入 它们 ， 以 便 注册 命令 。 我 决定 在 顶级 目录 的 microblog.py 文 
件 中 执行 此 操作 : 


microblog.py : 注册 命令 。 


from app import cli 


此 时 ， 运 行 flask --help 将 列 出 translate 命令 作为 选项 。 flask translate --help 将 显示 
我 定义 的 三 个 子 命令 : 
(venv) $ flask translate --help 
Usage: flask translate [OPTIONS] COMMAND [ARGS]... 
Translation and localization commands. 


Options: 
--help Show this message and exit. 


Commands: 
compile Compile all languages. 
init Initialize a new language. 


update Update all languages. 


所 以 现在 工作 流程 就 简便 多 了 ， 而 且 不 需要 记 住 长 而 复杂 的 命令 。 要 添加 新 的 语言 ， 请 使 
用 : 


(venv) $ flask translate init <language-code> 


在 更 改 O 和 10 语言 标记 后 更 新 所 有 语言 : 


(venv) $ flask translate update 


在 更 新 翻译 文件 后 编译 所 有 语言 : 


(venv) $ flask translate compile 


本 文 翻 译 自 The Flask Mega-Tutorial Part XIV: Ajax 


这 是 Flask Mega-Tutorial 系 列 的 第 十 四 部 分 ， 我 将 使 用 Microsoft 翻 译 服务 和 少许 JavaScript 来 
添加 实时 语言 翻译 功能 。 


在 本 章 中 ， 我 将 从 服务 器 端 开发 的 “安全 区 域 "脱离 ， 研 究 与 服务 器 端 同样 重要 的 客户 端 组 件 的 
功能 。 你 是 否 看 到 过 某 些 网 站 在 用 户 生 成 的 内 容 旁 边 显示 的 “翻译 ”链接 ? 这 些 链接 会 触发 非 
用 户 本 地 语言 内 容 的 实时 自动 翻译 。 翻译 的 内 容 通常 插入 原始 版 本 的 下 方 。 Google 将 其 显示 
为 外 语 搜索 结果 。 Facebook 在 用 户 动态 上 使 用 它 。 Twitter 在 推 文 上 使 用 它 。 今天 我 将 向 你 
展示 如 何 将 相同 的 功能 添加 到 Microblog ! 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


服务 器 端 与 客户 端 


迄今 为 止 ， 在 我 遵循 的 传统 服务 器 端 模 型 中 ， 有 一 个 客户 端 ( 由 用 户 驱 动 的 Web 浏 览 器 ) 向 
应 用 服务 器 发 出 HTTP 请 求 。 请 求 可 以 简单 地 请 求 HTML 页 面 ， 例 如 当 你 单 击 “ 个 人 主页 ”链接 
时 ， 或 者 它 可 以 触发 一 个 操作 ， 例 如 在 编辑 你 的 个 人 信息 之 后 单 击 提交 按钮 。 在 这 两 种 类 型 
的 请 求 中 ， 服 务 器 通过 直接 发 送 新 的 网 页 或 通过 发 送 重 定向 来 完成 请 求 。 然后 客户 端 用 新 的 
页 面 蔡 换 当 前 页 面 。 只 要 用 户 停留 在 应 用 的 网 站 上 ， 该 周期 就 会 重复 。 在 这 种 模式 下 ， 服 务 
器 完成 所 有 工作 ， 而 客户 端 只 显示 网 页 并 接受 用 户 输入 。 


有 一 种 不 同 的 模式 ， 客 户 端 扮演 更 积极 的 角色 。 在 这 个 模式 中 ， 客 户 端 向 服务 器 发 出 一 个 请 
求 ， 服 务 器 响应 一 个 网 页 ， 但 与 前 面 的 情况 不 同 ， 并 不 是 所 有 的 页 面 数据 都 是 HTML， 页 面 中 
也 有 部 分 代码 ， 通 常用 Javascript 编 写 。 一 旦 客户 端 收 到 该 页 面 ， 它 就 会 显示 HTML 部 分 ， 并 
执行 代码 。 从 那 时 起 ， 你 就 拥有 了 一 个 可 以 独立 工作 的 活动 客户 端 而 无 需 与 服务 器 进行 联 
系 或 只 有 很 少 联系 。 在 严格 的 客户 端 应 用 中 ， 整 个 应 用 通过 初始 页 面 请 求 下 载 到 客户 端 ， 然 
后 应 用 完全 在 客户 端 上 运行 ， 只 有 在 查询 或 者 变更 数据 时 才 与 服务 器 联系 。 这 种 类 型 的 应 用 
称 为 单 页 应 用 (SPAs) ° 


大 多 数 应 用 是 这 两 种 模式 的 混合 ， 并 结合 了 两 者 的 技术 特点 。 我 的 Microblog 应 用 主要 是 服务 
器 端 应 用 ， 但 今天 我 将 添加 一 些 客户 端 操作 。 为 了 实时 翻译 用 户 动 态 ， 客 户 端 浏览 器 将 异步 
请 求 发 送 到 服务 器 ， 服 务 器 将 响应 该 请 求 而 不 会 导致 页 面 刷新 。 然 后 客户 端 将 动态 地 将 翻译 
插入 当前 页 面 。 这 种 技术 被 称 为 Ajax)， 这 是 Asynchronous JavaScript 和 XML 的 简称 〈 尽 管 现 
在 XML 常 常 被 JSON 取 代 ) ° 


实时 翻译 的 工作 流程 


由 于 使 用 了 Flask-Babel， 本 应 用 对 外 语 有 很 好 的 支持 ， 可 以 支持 尽 可 能 多 的 语言 ， 只 要 我 找 
到 了 对 应 的 译文 。 但 是 遗漏 了 一 个 元 素 ， 用 户 将 会 用 他 们 自己 的 语言 发 表 动 态 ， 所 以 用 户 很 
可 能 会 用 应 用 未 知 的 语言 发 表 动 态 。 自动 翻译 的 质量 大 多 数 情况 下 不 怎么 样 ， 但 在 ， 如 果 你 
只 想 对 另 一 种 语言 的 文本 了 解 其 基本 含义 ， 这 已 经 足够 了 。 


这 正 是 Ajax 大 展 身手 的 好 机 会 ! 设想 主页 或 发 现 页 面 可 能 会 显示 若干 用 户 动 态 ， 其 中 一 些 可 
能 是 外 语 。 如 果 我 使 用 传统 的 服务 器 端 技术 实现 翻译 ， 则 翻译 请 求 会 导致 原始 页 面 被 替换 为 
新 页 面 。 事 实 是 ， 要 求 翻译 诸多 用 户 动态 中 的 一 条 ， 并 不 是 一 个 足够 大 的 动作 来 要 求 整 个 页 
面 的 更 新 ， 如 果 翻 译文 本 可 以 被 动态 地 插入 到 原始 文本 下 方 ， 而 剩 下 的 页 面 保持 原样 ， 则 用 
户 体验 更 加 出 色 。 


实时 自动 翻译 需要 几 个 步骤 。 首先 ， 我 需要 一 种 方法 来 识别 要 翻译 的 文本 的 源 语言 。 我 
要 知道 每 个 用 户 的 首选 语言 ， 因 为 我 想 仅 为 使 用 其 他 语言 发 表 的 动态 显示 “翻译 "链接 。 

当 提 供 翻 译 链接 并 且 用 户 点 击 它 时 ， 我 需要 将 Ajax 请 求 发 送 到 服务 器 ， 服 务 器 将 联系 第 三 方 
翻译 API。 一旦 服务 器 发 送 了 带 有 翻译 文本 的 响应 ， 客 户 端 JavaScript 代 码 将 动态 地 将 该 文本 
插入 到 页 面 中 。 你 一 定 注意 到 了 ， 这 里 有 一 些 特殊 的 问题 。 我 将 逐一 审视 这 些 问 题 。 


> 四 


B 


第 一 个 问题 是 确定 一 条 用 户 动态 的 语言 。 这 不 是 一 门 精确 的 科学 ， 因 为 不 能 确保 监测 结果 绝 
对 正确 ， 但 是 对 于 大 多 数 情况 ， 自 动 检测 的 效果 相当 好 。 在 Python 中 ， 有 一 个 称 

为 guess_language 的 语言 检测 库 ， 还 算 好 用 。 这 个 软件 包 的 原始 版 本 相当 陈旧， 从 未 被 移植 
到 Python 3， 因 此 我 将 安装 支持 Python 2 和 3 的 派生 版 本 : 


(venv) $ pip install guess-language_spirit 


计划 是 将 每 条 用 户 动态 提供 给 这 个 包 ， 以 党 试 确定 语言 。 由 于 做 这 种 分 析 有 点 费时 ， 我 不 想 
每 次 把 帖子 呈现 给 页 面 时 重复 这 项 工作 。 我 要 做 的 是 在 提交 时 为 帖子 设置 源 语言 。 检测 到 的 
语言 将 被 存储 在 post 表 中 。 


AP 


第 一 步 ， 添 加 language 字段 到 post 模型 : 


app/models.py : 添加 监测 到 的 语言 到 post 模型 : 


class Post(db.Model): 
Foara 
language = db.Column(db.String(5)) 


你 一 定 还 记得 ， 每 当 数 据 库 模 型 发 生变 化 时 ， 都 需要 生成 数据 库 迁 移 : 


(venv) $ flask db migrate -m "add language to posts" 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.autogenerate.compare] Detected added column 'post.language' 
Generating migrations/versions/2b017edaa9if_add_language_to_posts.py ... done 


然后 将 迁移 应 用 到 数据 库 : 


(venv) $ flask db upgrade 

INFO [alembic.runtime.migration] Context impl SQLiteImpl. 

INFO [alembic.runtime.migration] Will assume non-transactional DDL. 

INFO [alembic.runtime.migration] Upgrade ae346256b650 -> 2b017edaa9if, add language t 
o posts 


我 现在 可 以 在 提交 帖子 时 检测 并 存储 语言 : 
app/routes.py : 为 新 的 用 户 动态 保存 语言 字段 。 


from guess_language import guess_language 


@app.route('/', methods=['GET', 'POST']) 
@app.route('/index', methods=['GET', 'POST']) 
@login_required 
def index(): 
form = PostForm() 
if form.validate_on_submit(): 
language = guess_language(form.post.data) 
if language == 'UNKNOWN' or len(language) > 5: 
language = '' 
post = Post(body=form.post.data, author=current_user, 
language=language ) 
# a. 


有 了 这 个 变更 ， 每 次 发 表 动态 时 ， 都 会 通过 guess_language 函数 测试 文本 来 尝试 确 定语 言 。 
如 果 语言 监测 为 未 知 ， 或 者 如 果 我 得 到 意 想不到 的 长 字符 串 的 结果 ， 我 会 将 一 个 空 字符 串 保 
存 到 数据 库 中 以 安全 地 使 用 它 。 我 将 采用 约定 ， 将 任何 将 把 语言 设置 为 空 字 符 串 的 帖子 假定 
为 未 知 语言 。 


展示 一 个 “翻译 ”链接 


REŽO 我 现在 要 做 的 是 在 任何 不 是 当前 用 户 的 首选 语言 的 用 户 动态 下 ， 添 加 一 个 " 翻 
译 "链接 。 


app/templates/_post.html : 给 用 户 动态 添加 翻译 链接 。 


{% if post.language and post.language != g.locale %} 
<br><br> 

<a href="#">{{ _('Translate') }}</a> 

{% endif %} 


我 在 _post.html 子 模板 中 执行 此 操作 ， 以 便 此 功能 出 现在 显示 用 户 动态 的 任何 页 面 上 。 翻译 
链接 只 会 出 现在 检测 到 语言 种 类 的 动态 下 ， 并 且 必 须 满足 的 条 件 是 ， 这 种 语言 与 用 Flask- 
Babel 的 localeselector 装饰 器 装饰 的 函数 选择 的 语言 不 匹配 。 回想 一 下 第 十 三 章 所 选 语言 
环境 存储 为 g.locale ° 链接 文本 需要 以 Flask-Babel 可 以 翻译 的 方式 添加 ， 所 以 我 在 定义 它 
时 使 用 了 _() Wee 


请 注意 ， 我 还 没有 关联 此 链接 的 操作 。 首先 ， 我 想 弄 清楚 如 何 进行 实际 的 翻译 。 


使 用 第 三 方 翻 译 服 务 


两 种 主要 的 翻译 服务 是 Google Cloud Translation API 和 Microsoft Translator Text API。 两 者 
都 是 付费 服务 ， 但 微软 为 低频 少量 的 翻译 提供 了 免费 的 入 门 级 选项 。 谷歌 过 去 提供 免费 翻译 
服务 ， 但 现在 ， 即 使 是 最 低层 次 的 服务 也 需要 付费 。 因为 我 希望 能 够 在 不 产生 费用 的 情况 下 
尝试 翻译 ， 我 将 实施 Microsoft 的 解决 方案 。 


在 使 用 Microsoft Translator API 之 前 ， 你 需要 先 获得 微软 云 服 务 Azure 的 帐户 。 你 可 以 选择 免 
费 套餐 ， 但 在 注册 过 程 中 系统 会 要 求 你 提供 信用 卡号 ， 但 在 你 保持 该 级 别 的 服务 时 ， 你 的 卡 
不 会 被 收取 费用 。 

获得 Azure 帐 户 后 ， 转 到 Azure 门 户 并 单 击 左上 角 的 “New” 按 钮 ， 然 后 键入 或 选择 “Translator 


Text API” o 当 你 点 击 “Create” 按 钮 时 ， 将 看 到 一 个 表单 ， 并 可 以 在 其 中 定义 一 个 新 的 翻译 器 
资源 ， 然 后 将 其 添加 到 你 的 帐户 中 。 你 可 以 在 下 面 看 到 我 是 如 何 完成 表单 的 : 


Create 


Translator Text API 





* Name 
translator vV 


* Subscription 


Free Trial v 


* Pricing tier (View full pricing details) 


FO (2M Characters translated per month) v 


* Resource group 


© create new Use existing 


translator vV 


* Resource group location @ 
Central US Vv 


* | confirm | have read and understood the 
notice below. 


当 你 再 次 点 击 “Create" 按 钮 时 ， 翻 译 器 API 资 源 将 被 添加 到 你 的 帐户 中 。 几 秒 钟 之 后 ， 你 将 在 
顶 栏 中 收 到 通知 ， 说 明 部 署 了 翻译 器 资源 。 点 击 通知 中 的 “Go to resource” 按 钮 ， 然 后 点 击 左 
侧 栏 上 的 “Keys” 选 项 。 你 现在 将 看 到 两 个 Key， 分 别 标 记 为 “Key 1”" 和 “Key 2"”。 将 其 中 一 个 
Key 复 制 到 剪贴 板 ， 然 后 将 其 设置 到 终端 的 环境 变量 中 (如 果 使 用 的 是 Microsoft Windows ， 
请 用 set 替换 export ) 


(venv) $ export MS_TRANSLATOR_KEY=<paste- your -key-here> 


该 Key 用 于 验证 翻译 服务 ， 因 此 需要 将 其 添加 到 应 用 配置 中 : 


config.py: 添加 Microsoft Translator API key 到 配置 中 。 


class Config(object): 
# a 
MS_TRANSLATOR_KEY = os.environ.get('MS_TRANSLATOR_KEY' ) 


与 很 多 配置 值 一 样 ， 我 更 喜欢 将 它们 安装 在 环境 变量 中 ， 并 从 那里 将 它们 导入 到 Flask 配 置 
Po 对 于 允许 访问 第 三 方 服务 的 密 钥 或 密码 等 敏感 信息 ， 这 一 点 尤为 重要 。 你 绝对 不 想 在 代 
码 中 明确 写 出 它们 。 


Microsoft Translator API 是 一 个 接受 HTTP 请 求 的 Web 服 务 。 Python 中 有 若干 HTTP 客 户 端 ， 
但 最 常用 和 最 简单 的 就 是 requests 包 。 所 以 让 我 们 将 其 安装 到 虚拟 环境 中 : 


(venv) $ pip install requests 


在 下 面 ， 你 可 以 看 到 我 使 用 Microsoft Translator API 编 写 翻 译文 本 的 功能 。 我 来 新 增 一 
个 app/translate.py 模 块 : 


app/translate.py : 文本 翻译 函数 。 


import json 

import requests 

from flask_babel import _ 
from app import app 


def translate(text, source_language, dest_language): 
if 'MS_TRANSLATOR_KEY' not in app.config or \ 
not app.config['MS_TRANSLATOR_KEY']: 
return _('Error: the translation service is not configured. ') 
auth = {'Ocp-Apim-Subscription-Key': app.config['MS_TRANSLATOR_KEY' ]} 
r = requests.get('https://api.microsofttranslator.com/v2/Ajax.svc' 
'/Translate?text={}&from={}&to={}'. format ( 
text, source_language, dest_language), 
headers=auth) 
if r.status_code != 200: 
return _('Error: the translation service failed.') 
return json.loads(r.content .decode('utf-8-sig')) 


该 函数 定义 需要 翻译 的 文本 、 源 语言 和 目标 语言 为 参数 ， 并 返回 翻译 后 文本 的 字符 囊 。 它 首 
先 检查 配置 中 是 否 存 在 翻译 服务 的 Key， 如 果 不 存在 ， 则 会 返回 错误 。 错误 也 是 一 个 字符 
串 ， 所 以 从 外 部 看 ， 这 将 看 起 来 像 翻译 文本 。 这 可 确保 在 出 现 错误 时 用 户 将 看 到 有 意义 的 错 


误 消息 。 


requests 包 中 的 get() 方法 向 作为 第 一 个 参数 给 定 的 URL 发 送 一 个 带 有 GET 方 法 的 HTTP 请 
求 。 我 使 用 V2/Ajax.svc/Translate URL， 它 是 翻译 服务 中 的 一 个 端点 ， 它 将 翻译 内 容 荷载 为 
JSON 返 回 。 文 本 、 源 语言 和 目标 语言 都 需要 在 URL 中 分 别 命名 为 text ， from 和 to 作为 查 
询 字 符 串 参数 。 要 使 用 该 服务 进行 身份 验证 ， 我 需要 将 我 添加 到 配置 中 的 Key 传 递 给 该 服 
务 。 该 Key 需 要 在 名 为 Ocp-Apim-Subscription-Key 的 自 定 义 HTTP 头 中 给 出 。 我 创建 

了 auth 字典 ， 然 后 将 它 通过 headers 参数 传递 给 requests ° 


requests.get() 方法 返回 一 个 响应 对 象 ， 它 包含 了 服务 提供 的 所 有 细节 。 我 首先 需要 检查 和 
确认 状态 码 是 200， 这 是 成 功 请 求 的 代码 。 如 果 我 得 到 任何 其 他 代码 ， 我 就 知道 发 生 了 错 

误 ， 所 以 在 这 种 情况 下 ， 我 返回 一 个 错误 字符 串 。 如 果 状 态 码 是 200， 那 么 响应 的 主体 就 有 
一 个 带 有 翻译 的 JSON 编 码 字符 串 ， 所 以 我 需要 做 的 就 是 使 用 Python 标准 库 中 

的 json.loads() 函数 将 JSON 解 码 为 我 可 以 使 用 的 Python 字符 串 。 响应 对 象 的 content 属性 
包含 作为 字 节 对 象 的 响应 的 原始 主体 ， 该 属性 是 UTF-8 编 码 的 字符 序列 ， 需 要 先进 行 解码 ， 然 
后 发 送 给 json.loads() ° 


下 面 你 可 以 看 到 一 个 Python 控制 台 会 话 ， 我 演示 了 如 何 使 用 新 的 translate() BWA: 


>>> from app.translate import translate 

>>> translate('Hi, how are you today?', 'en', 'es') # English to Spanish 
"Hola, ¿cómo estas hoy?' 

>>> translate('Hi, how are you today?', 'en', 'de') # English to German 
"Are Hallo, how you heute?' 

>>> translate('Hi, how are you today?', 'en', 'it') # English to Italian 
"Ciao, come stai oggi?' 

>>> translate('Hi, how are you today?', 'en', 'fr') # English to French 
"Salut, comment allez-vous aujourd'hui ?" 


很 酷 ， 对 吧 ? 现在 是 时 候 将 此 功能 与 应 用 集成 在 一 起 了 。 


来 自 服务 器 的 Ajax 


我 将 从 实现 服务 器 端 部 分 开始 。 当 用 户 单 击 动态 下 方 显示 的 翻译 链接 时 ， 将 向 服务 器 发 出 异 
步 HTTP 请 求 。 我 将 在 下 一 节 中 向 你 展示 如 何 执行 此 操作 ， 因 此 现在 我 将 专注 于 实现 服务 器 处 
理 此 请 求 的 操作 。 


HY (Ajax) 请 求 类 似 于 我 在 应 用 中 创建 的 路 由 和 视图 函数 ， 唯 一 的 区 别 是 它 不 返回 HTML 或 
重 定向 ， 而 是 返回 数据 ， 格 式 为 XML 或 更 常见 的 JSON。 你 可 以 在 下 面 看 到 翻译 视图 函数 ， 
该 函数 调用 Microsoft Translator API， 然 后 返回 JSON 格 式 的 翻译 文本 : 


app/routes.py : X AHEM A BA o 


from flask import jsonify 
from app.translate import translate 


@app.route('/translate', methods=['POST']) 
@login_required 
def translate_text(): 
return jsonify({'text': translate(request.form['text'], 
request.form[ 'source_language'], 
request. form[ 'dest_language'])}) 


如 你 所 见 ， 相 当 简 单 。 我 以 post 请 求 的 形式 实现 了 这 条 路 由 。 关于 什么 时 候 使 
用 GET 或 post (或 者 还 没有 见 过 的 其 他 请 求 方法 ) > BHRABH HOM o 由 于 客户 端 将 
发 送 数据 ， 因 此 我 决定 使 用 post 请 求 ， 因 为 它 与 提交 表单 数据 的 请 求 类 似 。 


request.form 属性 是 Flask 用 提交 中 包含 的 所 有 数据 暴露 的 字典 。 当 我 使 用 Web 表 单 工作 
时 ， 我 不 需要 查看 request.form ， 因 为 Flask-WTF 可 以 为 我 工作 ， 但 在 这 种 情况 下 ， 实 际 上 
没有 Web 表 单 ， 所 以 我 必须 直接 访问 数据 。 


所 以 我 在 这 个 函数 中 做 的 是 调用 上 一 节 中 的 translate() 函数 ， 直 接 从 通过 请 求 提 交 的 数据 中 
传递 三 个 参数 。 将 结果 合并 到 单个 键 text 下 的 字典 中 ， 字 典 作为 参数 传递 给 Flask 

的 jsonify() 函数 ， 该 函数 将 字典 转换 为 JSON 格 式 的 有 效 载荷 。 jsonify() 返回 的 值 是 将 被 
发 送 回 客户 端的 HTTP 响 应 。 

例如 ， 如 果 客户 希望 将 字符 串 *Hello，World | "翻译 成 西班牙 语 ， 则 来 自 该 请 求 的 响应 将 具有 
以 下 有 效 载荷 : 


{ "text": "Hola, Mundo!" } 


来 自 客户 端的 Ajax 


因此 ， 现 在 服务 器 能 够 通过 /translate URL 提 供 翻 译 ， 当 用 户 单 击 我 上 面 添加 的 “翻译 ”链接 

时 ， 我 需要 调用 此 URL， 传 弟 需 要 翻译 的 文本 、 源 语言 和 目标 语言 。 如 果 你 不 熟悉 在 浏览 器 
中 使 用 JavaScript， 这 将 是 一 个 很 好 的 学 习 机 会 。 

在 浏览 器 中 使 用 JavaScript 时 ， 当 前 显示 的 页 面 在 内 部 被 表示 为 文档 对 象 模型 (DOM) 。 这 
是 一 个 引用 页 面 中 所 有 元 素 的 层次 结构 。 在 此 上 下 文中 运行 的 JavaScript 代 码 可 以 更 改 DOM 
以 触发 页 面 中 的 更 改 。 


我 们 首先 需要 讨论 的 是 ， 在 浏览 器 中 运行 的 JavaScript 代 码 如 何 获取 需要 发 送 到 服务 器 中 运行 
的 翻译 函数 的 三 个 参数 。 为 了 获得 文本 ， 我 需要 找到 包含 用 户 动态 正文 的 DOM 内 的 节点 并 获 
取 它 的 内 容 。 为 了 便于 识别 包含 用 户 动态 的 DOM 节 点 ， 我 将 为 它们 附加 一 个 唯一 的 ID。 如 果 
你 查看 _post.html 模 板 ， 则 呈现 用 户 动 态 正文 的 行 只 会 读 取 {{post.body}} ° 我 要 做 的 是 将 这 
些 内 容 包 装 在 一 个 <span> 元 素 中 。 这 不 会 在 视觉 上 改变 任何 东西 ， 但 它 给 了 我 一 个 可 以 插入 
标识 符 的 地 方 : 


app/templates/_post.html : 给 每 条 用 户 动态 添加 ID © 

<span id="post{{ post.id }}">{{ post.body }}</span> 
这 将 为 每 条 用 户 动 态 分 配 一 个 唯一 标识 符 ， 格 式 为 posti ， post2 等 ， 其 中 数字 与 每 条 用 户 
动态 的 数据 库 标 识 符 相 匹配 。 现在 每 条 用 户 动 态 都 有 一 个 唯一 的 标识 符 ， 给 定 一 个 ID 值 ， 我 


可 以 使 用 jQuery 定位 <span> 元 素 并 提取 其 中 的 文本 。 例如 ， 如 果 我 想 获得 ID 为 123 的 用 户 动 
态 的 文本 ， 我 可 以 这 样 做 : 


$('#post123').text() 


这 里 的 $ 符 号 是 jQuery 库 提 供 的 函数 的 名 称 。 ie ， 所 以 它 已 经 被 Flask- 
Bootstrap 包含 。 # 是 jQuery 使 用 的 “选择 器 "语法 的 一 部 分 ， 这 意味 着 接 下 来 是 元 素 的 ID © 


我 也 希望 有 一 个 地 方 可 以 在 我 从 服务 器 收 到 翻译 文本 后 插入 翻译 文本 。 我 要 做 的 是 将 “ 翻 
译 "链接 替换 为 翻译 文本 ， 因 此 我 还 需要 为 该 节点 提供 唯一 标识 符 : 


app/templates/_post.html : 为 翻译 链接 添加 ID。 


<span id="translation{{ post.id }}"> 
<a href="#">{{ _('Translate') }}</a> 
</span> 


因此 ， 现 在 对 于 一 个 给 定 的 用 户 动态 ID， 我 有 一 个 用 于 用 户 动 态 的 post <ID> 节点 和 一 个 对 
应 的 translation <ID> 节点 ， 我 可 以 在 用 翻译 后 的 文本 替换 翻译 链接 时 用 到 它们 。 

下 一 步 是 编写 一 个 可 以 完成 所 有 翻译 工作 的 函数 。 该 函数 将 利用 输入 和 输出 DOM 节 点 以 及 源 
语言 和 目标 语言 ， 向 服务 器 发 出 携带 必须 的 三 个 参数 的 异步 请 求 ， 并 在 服务 器 响应 后 用 翻译 
后 的 文本 替换 翻译 链接 。 这 听 起 来 像 很 多 工作 ， 但 实现 相当 简单 : 


app/templates/base.html : 客户 端 翻译 函数 。 


{% block scripts %} 
<script> 
function translate(sourceElem, destElem, sourceLang, destLang) { 
$(destElem).html('<img src="{{ url_for('static', filename='loading.gif') } 


Dy 
$.post('/translate', { 
text: $(sourceElem).text(), 
source_language: sourceLang, 
dest_language: destLang 
}).done(function(response) { 
$(destElem).text(response['text']) 
}).fail(function() { 
$(destElem).text("{{ _('Error: Could not contact server.') }}"); 
}); 
</script> 


{% endblock %} 


前 两 个 参数 是 用 户 动态 和 翻译 链接 节点 的 唯一 ID， 后 两 个 参数 是 源 语言 和 目标 语言 代码 。 


该 函数 从 一 个 很 好 的 接触 开始 : 它 添加 一 个 加 载 器 替换 翻译 链接 ， 以 便 用 户 知 道 翻 译 正 在 进 
行 中 。 这 是 通过 使 用 $(destElem) .html() 函数 完成 的 ， 它 用 基于 <img> 元 素 的 新 HTML 内 容 
替换 定义 为 翻译 链接 的 原始 HTML。 对 于 加 载 器 ， 我 将 使 用 一 个 小 的 动画 GIF， 它 已 添加 到 
Flask 为 静态 文件 保留 的 app/static 目 录 中 。 为 了 生成 引用 这 个 图 像 的 URL， 我 使 

用 url _for() 函数 ， 传递 特殊 的 路 由 名 称 static 并 给 出 图 像 的 文件 名 作为 参数 。 你 可 以 在 本 
章 的 下 载 包 中 找到 /oading.gif 图 像 。 


现在 我 用 一 个 优雅 的 加 载 器 代替 了 翻译 链接 ， 以 便 用 户 知道 要 等 待 翻译 出 现 。 下 一 步 是 将 
scia Ja 节 中 定义 的 /translate URL。 为 此 ， 我 也 将 使 用 jQuery， 本 处 使 
用 $ .post() HA ° 个 函数 以 一 种 类 似 于 浏览 器 提交 Web 表 单 的 格式 向 服务 器 提交 数据 ， 


a, 因为 它 允 许 Flask 将 这 | paren form 字典 中 。 $ .post() 的 参数 是 两 
， 第 一 个 是 eau 二 个 是 包含 服务 器 期 望 的 三 个 数据 项 的 字典 (或 者 称 之 为 
因为 这 些 是 在 JavaScript 中 调用 的 ) 。 


你 可 能 知道 JavaScript 对 回调 函数 (或 者 称 为 promises 的 更 高 级 的 回调 形式 ) 友好 。 现在 要 
做 的 就 是 说 明 一 旦 这 个 请 求 完成 并 且 浏 览 器 接收 到 响应 ， 我 想 完成 的 事情 。 在 JavaScript 中 
没有 需要 等 待 的 事情 ， 一 切 都 是 异步 。 我 需要 做 的 是 提供 一 个 回调 函数 ， 浏 览 器 在 接收 到 响 
应 时 调用 它 。 而 且 ， 为 了 使 所 有 内 容 尽 可 能 健壮 ， 我 想 指出 在 出 现 错误 的 情况 下 该 怎么 做 ， 
以 作为 处 理 错 误 的 第 二 个 回调 函数 。 有 几 种 方法 可 以 指定 这 些 回调 ， 但 在 这 种 情况 下 ， 使 用 
promises 可 以 使 代码 更 加 清晰 。 语 法 如 下 : 


$.post(<url>, <data>).done(function(response) { 
// success callback 

}).fail(function() { 
// error callback 

}) 


promise 语 法 允许 将 $ ,post() 调用 的 返回 值 " 传 入 "回调 函数 作为 参数 。 在 成 功 回调 中 ， 我 所 
需要 做 的 就 是 使 用 翻译 后 的 文本 调用 $(destElem) .text() ， 该 文本 在 字典 中 text TF ° 在 

出 现 错误 的 情况 下 ， 我 也 是 这 样 做 的 ， 但 是 我 显示 的 文本 是 一 条 通用 的 错误 消息 ， 我 会 确保 
它 会 作为 可 翻译 的 文本 编 入 基础 模板 中 。 


所 以 现在 唯一 剩 下 的 就 是 通过 用 户 点 击 翻译 链接 来 触发 具有 正确 参数 的 translate() BA 
存在 若干 方法 可 以 做 到 这 一 点 ， 我 要 做 的 是 将 该 函数 的 调用 谋 入 链接 的 href 属性 中 : 


app/templates/_post.html : 翻译 链接 处 理 器 。 


<span id="translation{{ post.id }}"> 
<a href="javascript:translate( 
'#post{{ post.id }}', 
'#translation{{ post.id }}', 


'{{ post.language }}', 
'{{ g.locale }}');">{{ _('Translate') }}</a> 
</span> 


链接 的 href AA TA ZIET JavaScripti > wR ERA javascript: 前 级 的 话 ， 那 么 这 

是 一 种 方便 的 方式 来 调用 翻译 函数 。 因为 这 个 链接 将 在 客户 端 请 求 页 ep ， 
所 以 我 可 以 使 用 {{}} 表达 式 来 为 函数 生成 四 个 参数 。 每 条 用 户 动态 都 有 自己 的 翻译 链接 ， 
以 及 其 唯一 生成 的 参数 。 post <ID> 和 translation <ID> 需要 泻 染 具体 的 ID， 它 们 都 需要 在 
被 使 用 时 加 上 # 前 级 。 


现在 实时 翻译 功能 已 经 完成 ! 如 果 你 在 环境 中 设置 了 有 效 的 Microsoft Translator API Key > 
则 现在 应 该 能 够 触发 翻译 。 假设 你 的 浏览 器 设置 为 偏好 英语 ， 则 需要 使 用 其 他 语言 撰写 文章 
以 查看 “翻译 ”链接 。 下面 你 可 以 看 到 一 个 例子 : 


Explore - Microblog 


一 


Microblog 


Hi, miguel! 


miguel said a few seconds ago 
Este articulo fue muy interesante. 





This article was very interesting. 





在 本 章 中 ， 我 介绍 了 一 些 需 要 翻译 成 应 用 支持 的 所 有 语言 的 新 文本 ， 因 此 有 必要 更 新 翻译 目 


录 : 


(venv) $ flask translate update 


对 于 你 自己 的 项 目 ， 需 要 编辑 每 个 语言 存储 库 中 的 messages.po 文 件 以 包 
译 ， 不 过 我 已 经 在 本 章 的 下 载 包 或 GitHub 存 储 库 中 创建 了 西班牙 语 翻译 。 


要 完成 新 的 翻译 ， 还 需要 执行 编译 : 


(venv) $ flask translate compile 


这 些 新 测试 的 翻 


本 文 翻 译 自 The Flask Mega-Tutorial Part XV: A Better Application Structure 
这 是 Flask Mega-Tutorial 系 列 的 第 十 五 部 分 ， 我 将 使 用 适用 于 大 型 应 用 的 风格 重 构 本 应 用 。 


Microblog 已 经 是 一 个 初 具 规模 的 应 用 了 ， 所 以 我 认为 这 是 讨论 Flask 应 用 如 何在 持续 增长 中 不 
会 变 得 混乱 和 难以 管理 的 好 时 机 。 Flask 是 一 个 框架 ， 旨 在 让 你 选择 以 任何 方式 来 组 织 项 目 ， 
基于 该 理念 ， 在 应 用 日 益 庞 大 或 者 技能 水 平 变 化 的 时 候 ， 才 有 可 能 更 改 和 调整 其 结构 。 


在 本 章 中 ， 我 将 讨论 适用 于 大 型 应 用 的 一 些 模式 ， 并 且 为 了 演示 他 们 ， 我 将 对 Microblog 项 目 
的 结构 进行 一 些 更 改 ， 目 标 是 使 代码 更 易于 维护 和 组 织 。 当然 ， 在 站 正 的 Flask 精 神 中 ， 我 鼓 
励 你 在 尝试 决定 组 织 自 己 的 项 目的 方式 时 仅仅 将 这 些 更 改作 为 参考 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


目前 的 局 限 性 


目前 状态 下 的 应 用 有 两 个 基本 问题 。 如 果 你 观察 应 用 的 组 织 方式 ， 你 会 注意 到 有 几 个 不 同 的 
子 系统 可 以 被 识别 ， 但 支持 它们 的 代码 都 混合 在 了 一 起 ， 没 有 任何 明确 的 界限 。 我 们 来 回顾 
一 下 这 些 子 系统 是 什么 : 


e 用 户 认 证 子 系统 ， 包 括 app/routes.py 中 的 一 些 视图 函数 ，app/forms.py 中 的 一 些 表 
单 ，app/templates 中 的 一 些 模 板 以 及 *app/email.py 中 的 电子 邮件 支持 。 

e 错误 子 系 统 ， 它 在 app/errors.py 中 定义 了 错误 处 理 程 序 并 在 app/templates 中 定义 了 模 
板 。 

o 核心 应 用 功能 ， 包 括 显 示 和 撰写 用 户 动态 ， 用 户 个 人 主页 和 关注 以 及 用 户 动 态 的 实时 翻 
译 ， 这 些 功能 遍布 大 多 数 应 用 模块 和 模板 。 


思考 这 三 个 子 系统 以 及 它们 组 织 的 方式 ， 你 可 能 会 注意 到 这 样 一 个 模式 。 到 目前 为 止 ， 我 一 
直 遵 循 的 组 织 逻 辑 是 不 同 的 应 用 功能 归属 到 其 专属 的 模块 。 这 些 模 块 之 中 ， 一 个 用 于 视图 区 
数 ， 一 个 用 于 Web 表 单 ， 一 个 用 于 错误 ， 一 个 用 于 电子 邮件 ， 一 个 目录 用 于 存放 HTML 模 板 等 
等 。 虽 然 这 是 一 个 对 小 项 目 有 意义 的 组 织 结构 ， 但 是 一 旦 项 目 开始 增长 ， 它 往往 会 使 其 中 的 
一 些 模 块 变 得 非常 大 而 且 杂 乱 无 章 。 


要 想 清晰 地 看 到 问题 的 一 种 方法 ， 是 思考 如 何 通过 尽 可 能 多 地 重复 使 用 这 一 项 目 来 开始 第 二 
个 项 目 。 例 如 ， 用 户 身份 验证 部 分 应 该 在 其 他 应 用 中 也 能 运行 良好 ， 但 如 果 你 想 按 原样 使 用 
该 代码 ， 则 必须 进入 多 个 模块 并 将 相关 部 分 复制 /粘贴 到 新 项 目的 新 文件 中 。 看 到 这 是 多 么 不 
方便 了 吗 ? 如 果 这 个 项 目 将 所 有 与 认证 相关 的 文件 从 应 用 的 其 余部 分 中 分 离 出 来 ， 会 不 会 更 
好 ? Flask 的 blueprints 功 能 有 助 于 实现 更 实用 的 组 织 结 构 ， 从 而 更 轻松 地 重用 代码 。 


还 有 第 二 个 问题 ， 虽 然 它 不 太 明 显 。 Flask 应 用 实例 在 app/_init .py 中 被 创建 为 一 个 全 局 
变量 ， 然 后 又 被 很 多 应 用 模块 导入 。 虽然 这 本 身 并 不 是 问题 ， 但 将 应 用 实例 作为 全 局 变量 可 
能 会 使 某 些 情况 复杂 化 ， 特 别 是 与 测试 相关 的 情景 。 想象 一 下 你 想 要 在 不 同 的 配置 下 测试 这 
个 应 用 。 由 于 应 用 被 定义 为 全 局 变量 ， 实 际 上 没有 办 法 使 用 不 同 配置 变量 来 实例 化 的 两 个 应 


用 实例 。 AAPM HIE > HA MAAS AA A > ALMA EAM ATR 
改 ， 就 会 影响 稍 后 运行 的 其 他 测试 。 理想 情况 下 ， 你 希望 所 有 测试 都 在 原始 应 用 实例 上 运行 
的 。 


你 可 以 在 tests.py 模 块 中 看 到 我 正在 使 用 的 应 用 实例 化 之 后 修改 配置 的 技巧 ， 以 指示 测试 时 使 
用 内 存 数 据 库 而 不 是 黑 认 的 SQLite 数 据 库 。 我 贤 的 没有 其 他 办 法 来 更 改 已 配置 的 数据 库 ， 因 
为 在 测试 开始 时 已 经 创建 和 配置 了 应 用 。 对 于 这 种 特殊 情况 ， 对 已 配置 的 应 用 实例 修改 配置 
似乎 可 以 运行 ， 但 在 其 他 情况 下 可 能 不 会 ， 并 且 在 任何 情况 下 ， 这 是 一 种 不 推荐 的 做 法 ， 因 
AAMT AES FH Ke HBL FF A VA RS BUG © 


更 好 的 解决 方案 是 不 将 应 用 设置 为 全 局 变量 ， 而 是 使 用 应 用 工厂 函数 在 运行 时 创建 它 。 这 将 
是 一 个 接受 配置 对 象 作为 参数 的 函数 ， 并 返回 一 个 配置 完毕 的 Flask 应 用 实例 。 如 果 我 能 够 通 
过 应 用 工厂 函数 来 修改 应 用 ， 那 么 编写 需要 特殊 配置 的 测试 会 变 得 很 容易 ， 因 为 每 个 测试 都 
可 以 创建 它 各 自 的 应 用 。 


在 本 章 中 ， 我 将 通过 为 上 面 提 到 的 三 个 子 系统 重 构 应 用 来 介绍 blueprints。 展示 更 改 的 详细 列 
表 有 些 不 切实 际 ， 因 为 几乎 应 用 中 每 个 文件 都 有 少许 变化 ， 所 以 我 将 讨论 重 构 的 步骤 ， 然 后 
你 可 以 下 载 更 改 后 的 应 用 。 


Blueprints 


在 Flask 中 ，blueprint 是 代表 应 用 子 集 的 逻辑 结构 。 blueprint 可 以 包括 路 由 ， 视 图 函数 ， 表 
单 ， 模 板 和 静态 文件 等 元 素 。 如 果 在 单独 的 Python 包 中 编写 blueprint， 那 么 你 将 拥有 一 个 封 
装 了 应 用 特定 功能 的 组 件 。 


Blueprint 的 内 容 最 初 处 于 休眠 状态 。 为 了 关联 这 些 元 素 ，blueprint 需 要 在 应 用 中 注册 。 在 注 
册 过 程 中 ， 需 要 将 添加 到 blueprint 中 的 所 有 元 素 传递 给 应 用 。 因此 ， 你 可 以 将 blueprint 视 为 
应 用 功能 的 临时 存储 ， 以 帮助 组 织 代 码 。 


错误 处 理 Blueprint 


我 创建 的 第 一 个 blueprint 用 于 封装 对 错误 处 理 程序 的 支持 。 该 blueprint 的 结构 如 下 


app/ 
errors/ <-- blueprint package 
__init__.py <-- blueprint creation 
handlers. py <-- error handlers 
templates/ 
errors/ <-- error templates 
404. html 
500.htm1 


__init__.py <-- blueprint registration 


实质 上 ， 我 所 做 的 是 将 9pp/errors.py 模 块 移动 到 app/errors/handlers.py 中 ， 并 将 两 个 错误 模板 
移动 到 app/templates/errors 中 ， 以 便 将 它们 与 其 他 模板 分 开 。 我 还 必须 在 两 个 错误 处 理 程序 
中 更 改 render_template() 调用 以 使 用 新 的 errors 模 板子 目录 。 之 后 ， 我 将 blueprint 创 建 添加 
到 app/errors/init.py 模 块 ， 并 在 创建 应 用 实例 之 后 ， 将 blueprint 注 册 到 app/init.py。 


我 必须 提 一 下 ，Flask blueprints 可 以 为 自己 的 模板 和 静态 文件 配置 单独 的 目录 。 我 已 决定 将 
模板 移动 到 应 用 模板 目录 的 子 目 录 中 ， 以 便 所 有 模板 都 位 于 一 个 层次 结构 中 ， 但 是 如 果 你 硕 
望 在 blueprint 中 包含 属于 自己 的 模板 ， 这 也 是 支持 的 。 例如， 如 果 向 Blueprint() 构造 函数 
添加 template_folder='templates' 参数 ， 则 可 以 将 错误 blueprint 的 模板 存储 


在 app/errors/templates 目 录 中 。 
创建 blueprint 与 创建 应 用 非常 相似 。 这 是 在 blueprint 的 init__.py 模块 中 完成 的 : 


app/errors/__init__.py : 错误 blueprint。 


from flask import Blueprint 
bp = Blueprint('errors', _ name_) 


from app.errors import handlers 


Blueprint 类 获取 blueprint 的 名 称 ， 基 础 模块 的 名 称 (通常 在 Flask 应 用 实例 中 设置 

为 _name  ) 以 及 一 些 可 选 参 数 (在 这 种 情况 下 我 不 需要 这 些 参 数 ) © Blueprint 对 象 创建 
后 ， 我 导入 了 handlers.py 模 块 ， 以 便 其 中 的 错误 处 理 程序 在 blueprint 中 注册 。 该 导入 位 于 底 
部 以 避免 循环 依赖 。 

在 handlers.py 模 块 中 ， 我 放 育 使 用 @app.errornandler 装饰 器 将 错误 处 理 程序 附加 到 应 用 程 
序 ， 而 是 使 用 blueprint 的 @bp.app_errorhandler 装饰 器 。 尽 管 两 个 装饰 器 最 终 都 达到 了 相同 
的 结果 ， 但 这 样 做 的 目的 是 试图 使 blueprint 独 立 于 应 用 ， 使 其 更 具 可 移植 性 。 我 还 需要 修改 两 
个 错误 模板 的 路 径 ， 因为 它们 被 移动 到 了 新 errors 子 目录 。 


完成 错误 处 理 程序 重 构 的 最 后 一 步 是 向 应 用 注册 blueprint : 
app/init.py : 向 应 用 注册 错误 blueprint。 


app = Flask(__name ) 
# wa. 


from app.errors import bp as errors_bp 
app.register_blueprint(errors_bp) 


# ... 


from app import routes, models # <-- remove errors from this import! 


为 了 注册 blueprint， 将 使 用 Flask 应 用 实例 的 register_blueprint() 方法 。 在 注册 blueprint 
时 ， 任 何 视 图 流 数 ， 模 板 ， 静 态 文 件 ， 错 误 处 理 程序 等 均 连 接 到 应 用 。 我 将 blueprint 的 导入 
放 在 app.register_blueprint() 的 上 方 ， 以 避免 循环 依赖 。 


用 户 认 证 Blueprint 


将 应 用 的 认证 功能 重 构 为 blueprint 的 过 程 与 错误 处 理 程序 的 过 程 非常 相似 。 以 下 是 重 构 为 
blueprint 的 目录 层次 结构 : 


app/ 

auth/ <-- blueprint package 
__init__.py <-- blueprint creation 
email.py <-- authentication emails 
forms.py <-- authentication forms 
routes. py <-- authentication routes 

templates/ 
auth/ <-- blueprint templates 

login. html 


register. html 
reset_password_request .html 
reset_password. html 
__init__.py <-- blueprint registration 


为 了 创建 这 个 blueprint， 我 必须 将 所 有 认证 相关 的 功能 移 到 为 blueprint 创 建 的 新 模块 中 。 这 
包括 一 些 视图 函数 ，Web 表 单 和 支持 功能 ， 例 如 通过 电子 邮件 发 送 密码 重 设 token 的 功能 。 我 
还 将 模板 移动 到 一 个 子 目录 中 ， 以 将 它们 与 应 用 的 其 余部 分 分 开 ， 就 像 我 对 错误 页 面 所 做 的 
那样 。 


在 blueprint 中 定义 路 由 时 ， 使 用 @bp.route 装饰 器 来 代替 @app.route 装饰 器 。 

在 url for() 中 用 于 构建 URL 的 语法 也 需要 进行 更 改 。 对 于 直接 附加 到 应 用 的 常规 视图 遂 
数 ，url for() 的 第 一 个 参数 是 视图 函数 名 称 。 但 当 在 blueprint 中 定义 路 由 时 ， 该 参数 必须 
包含 blueprint 名 称 和 视图 部 数 名 称 ， 并 以 句点 分 隔 。 因此， 我 不 得 不 用 诸 

如 url_for('auth.login') 的 代码 替换 所 有 出 现 的 url_for('login') 代码 ， 对 于 其 余 的 视图 遂 
数 也 是 如 此 。 


注册 auth blueprint 到 应 用 时 ， 我 使 用 了 些许 不 同 的 格式 : 
app/__init__.py : 注册 用 户 认 证 blueprint 到 应 用 。 


GA an 

from app.auth import bp as auth_bp 
app.register_blueprint(auth_bp, url_prefix='/auth') 
# aa’ 


在 这 种 情况 下 ” register_blueprint() 调用 接收 了 一 个 额 外 的 参数 ， url_prefix ° 这 完全 是 
可 选 的 ，Flask 提 供 了 给 blueprint 的 路 由 添加 URL 前 级 的 选项 ， 因 此 blueprint 中 定义 的 任何 路 
由 都 会 在 其 完整 URL 中 获取 此 前 级 。 在 许多 情况 下 ， 这 可 以 用 来 当成 “命名 空间 *”， 它 可 以 将 
blueprint 中 的 所 有 路 由 与 应 用 或 其 他 blueprint 中 的 其 他 路 由 分 开 。 对 于 用 户 认 证 ， 我 认为 让 
所 有 路 由 以 /auth 开 头 很 不 错 ， 所 以 我 添加 了 该 前 级 。 所 以 现在 登录 URL 将 会 

是 http:/localhost:5000/auth/login。 因为 我 使 用 url_for() 来 生成 URL， 所 有 URL 都 会 自动 合 


FATA ° 


+. | Blueprint 


第 三 个 blueprint 包 含 核心 应 用 逻辑 。 重 构 这 个 blueprint 和 前 两 个 blueprint 的 过 程 一 样 。 我 给 
这 个 blueprint 命 名 为 main > ALMA ARA BAH uri foro 调用 都 必须 添加 一 

main. 前 级 。 鉴于 这 是 应 用 的 核心 功能 ， 我 决定 将 模板 留 在 原来 的 位 置 。 这 不 会 有 什么 问 
题 ， 因 为 我 已 将 其 他 两 个 blueprint 中 的 模板 移动 到 子 目录 中 了 。 


应 用 工厂 模式 


正如 我 在 本 章 的 介绍 中 所 提 到 的 ， 将 应 用 设置 为 全 局 变量 会 引入 一 些 复杂 性 ， 主 要 是 以 某 些 
测试 场景 的 局 限 性 为 形式 。 在 我 介绍 blueprint 之 前 ， 应 用 必须 是 一 个 全 局 变量 ， 因 为 所 有 的 
视图 函数 和 错误 处 理 程序 都 需要 使 用 来 自 app 的 装饰 器 来 修饰 ， 比 如 @app.route ° 但 是 现在 
所 有 的 路 由 和 错误 处 理 程序 都 被 转移 到 了 blueprint 中 ， 因 此 保持 应 用 全 局 性 的 理由 就 不 够 充分 
Fe 


所 以 我 要 做 的 是 添加 一 个 名 为 create ap) 的 函数 来 构造 一 个 Flask 应 用 实例 ， 并 消除 全 局 变 
量 转换 并 非 容 多 > 我 不 得 不 理 清 一 些 复杂 的 东西 ’ 但 我 们 先 来 看 看 应 用 工厂 函数 : 


app/init.py : 应 用 工厂 函数 。 


# ,,， 

db = SQLAlchemy() 

migrate = Migrate() 

login = LoginManager ( ) 

login.login_view = '‘auth.login' 

login.login_message = _1('Please log in to access this page.') 
mail = Mail() 

bootstrap = Bootstrap() 

moment = Moment() 

babel = Babel() 


def create_app(config_class=Config): 
app = Flask(__name_ ) 
app.config.from_object(config_class) 


db.init_app(app) 
migrate.init_app(app, db) 
login.init_app(app) 
mail.init_app(app) 
bootstrap.init_app(app) 
moment .init_app(app) 
babel.init_app(app) 


# ... no changes to blueprint registration 


if not app.debug and not app.testing: 
# ... no changes to logging setup 


return app 


你 已 经 看 到 ， 大 多 数 Flask 插 件 都 是 通过 创建 插件 实例 并 将 应 用 作为 参数 传递 来 初始 化 的 。 当 
应 用 不 再 作为 全 局 变量 时 ， 有 一 种 替代 模式 ， 插 件 分 成 两 个 阶段 进行 初始 化 。 插件 实例 首先 
像 前 面 一 样 在 全 局 范围 内 创建 ， 但 没有 参数 传递 给 它 。 这 会 创建 一 个 未 附加 到 应 用 的 插件 实 


例 。 当 应 用 实例 在 工厂 函数 中 创建 时 ， 必 须 在 插件 实例 上 调用 init_app() 方法 ， 以 将 其 绑 定 
到 现在 已 知 的 应 用 。 


在 初始 化 期 间 执 行 的 其 他 任务 保持 不 变 ， 但 会 被 移 到 工厂 函数 而 不 是 在 全 局 范围 内 。 这 包括 
blueprint 和 日 志 配 置 的 注册 。 请 注意 ， 我 在 条 件 中 添加 了 一 个 not app.testing T° ATR 
定 是 否 启 用 电子 邮件 和 文件 日 志 ， 以 便 在 单元 测试 期 间 跳 过 所 有 这 些 日 志 记 录 。 由 于 在 配置 
中 TESTING 变量 在 单元 测试 时 会 被 设置 为 True ， 因 此 app.testing 标志 在 运行 单元 测试 时 将 


变 为 True ° 


那么 谁 来 调用 应 用 程 工厂 函数 呢 ? 最 明显 使 用 此 函数 的 地 方 是 处 于 顶级 目录 的 microblog.py 
脚本 ， 它 是 唯一 会 将 应 用 设置 为 全 局 变量 的 模块 。 另 一 个 调用 该 工厂 函数 的 地 方 是 tests.py ， 
我 将 在 下 一 节 中 更 详细 地 讨论 单元 测试 。 


正如 我 上 面 提 到 的 ， 大 多 数 对 app 的 引用 都 是 随 着 blueprint 的 引入 而 消失 的 ， 但 是 我 仍然 需 
要 解决 代码 中 的 一 些 问 题 。 例 如 ，app/models.py、app/translate.py 和 app/main/routes.py 模 
块 都 引用 了 app.config ° 幸运 的 是 ，Flask 开 发 人 员 试 图 使 视图 函数 很 容易 地 访问 应 用 实 

例 ， 而 不 必 像 我 一 直 在 做 的 那样 导入 它 。 Flask 提 供 的 current_app 变量 是 一 个 特殊 的 “上 下 
文 ? 变 量 ，Flask 在 分 派 请 求 之 前 使 用 应 用 初始 化 该 变量 。 你 之 前 已 经 看 到 另 一 个 上 下 文 变 
量 ， 即 存储 当前 语言 环境 的 g 变量 。 这 两 个 变量 ， 以 及 Flask-Login 的 current_user 和 其 他 
一 些 你 还 没有 看 到 的 东西 ， 是 “魔法 "变量 ， 因 为 它们 像 全 局 变量 一 样 工 作 ， 但 只 能 在 处 理 请 求 
期 间 且 在 处 理 它 的 线程 中 访问 。 


用 Flask 的 current_app 变量 替换 app 就 不 需要 将 应 用 实例 作为 全 局 变量 导入 。 通过 简单 的 搜 
索 和 替换 ， 我 可 以 毫 无 困难 地 用 current_app.config 替换 对 app.config 的 所 有 引用 。 


app/email.py 模 块 提出 了 一 个 更 大 的 挑战 ， 所 以 我 从 须 使 用 一 个 小 技巧 : 


app/email.py : 将 应 用 实例 传递 给 另 一 个 线程 。 


from app import current_app 


def send_async_email(app, msg): 
with app.app_context(): 
mail.send(msg) 


def send_email(subject, sender, recipients, text_body, html_body): 
msg = Message(subject, sender=sender, recipients=recipients) 
msg.body = text_body 
msg.html = html_body 
Thread(target=send_async_email, 
args=(current_app._get_current_object(), msg)).start() 


在 send_email() 函数 中 ， 应 用 实例 作为 参数 传递 给 后 台 线 程 ， 后 台 线 程 将 发 送 电子 邮件 而 不 
阻塞 主 应 用 程序 : 在 作为 后 台 线 程 运行 的 send_async_email() 函数 中 直接 使 用 current_app 将 
不 会 奏效 ， 因 为 current_app 是 一 个 与 处 理 客户 端 请 求 的 线程 绑 定 的 上 下 文 感知 变量 。 在 另 一 
个 线程 中 ” current_app 没有 赋值 直接 将 current_app 作为 参数 传递 给 线程 对 象 也 不 会 有 
效 ， 因 为 current_app 实际 上 是 一 个 代理 对 象 ， 它 被 动态 地 映射 到 应 用 实例 。 因 此 ， 传 递 代理 


对 象 与 直接 在 线程 中 使 用 current_app 相同 。 我 需要 做 的 是 访问 存储 在 代理 对 象 中 的 实际 应 用 
程序 实例 ， 并 将 其 作为 app 参数 传递 。 current_app._get_current_object() 表达 式 从 代理 对 
象 中 提取 实际 的 应 用 实例 ， 所 以 它 就 是 我 作为 参数 传递 给 线程 的 。 


另 一 个 环 手 的 模块 是 app/clijpy， 它 实现 了 一 些 用 于 管理 语言 翻译 的 快捷 命令 。 在 这 种 情况 
F> current_app 变量 不 起 作用 ， 因 为 这 些 命令 是 在 启动 时 注册 的 ， 而 不 是 在 处 理 请 求 期 间 
(这 是 唯一 可 以 使 用 current_app 的 时 间 段 ) 注册 的 。 为 了 在 这 个 模块 中 删除 对 app 的 引 
用 ， 我 使 用 了 另 一 个 技巧 ， 将 这 些 自 定义 命令 移动 到 一 个 将 app 实例 作为 参数 

的 register() 函数 中 : 


app/cli.py : 注册 自 定 义 应 用 命令 。 


import os 
import click 


def register(app): 
@app.cli.group() 
def translate(): 
"""Translation and localization commands.""" 
pass 


@translate.command() 
@click.argument('lang' ) 
def init(lang): 
"""Tnitialize a new language.""" 
H cent 


@translate.command() 

def update(): 
"""Update all languages.""" 
# ... 


@translate.command() 
def compile(): 


"""Compile all languages.""" 
# ... 


KJ & Mmicroblog.py F AARAA register() 函数 。 以 下 是 完成 重 构 后 的 microblog.py : 


microblog.py : 重 构 后 的 主 应 用 模块 。 
from app import create_app, db, cli 
from app.models import User, Post 


app = create_app() 
cli.register (app) 


@app.shell_context_processor 


def make_shell_context(): 
return {'db': db, 'User': User, 'Post!' :Post} 


单元 测试 的 改进 


正如 我 在 本 章 开 头 所 暗示 的 ， 到 目前 为 止 ， 我 所 做 的 很 多 工作 都 是 为 了 改进 单元 测试 工作 流 
程 。 在 运行 单元 测试 时 ， 要 确保 应 用 的 配置 方式 不 会 污染 开发 资源 (如 数据 库 ) 。 


tests.py 的 当前 版 本 采用 了 应 用 实例 化 之 后 修改 配置 的 技巧 ， 这 是 一 种 危险 的 做 法 ， 因 为 并 不 
是 所 有 类 型 的 更 改 都 会 在 修改 之 后 才 生 效 。 我 想 要 的 是 有 机 会 在 添加 到 应 用 之 前 指定 我 想 要 
的 测试 配置 项 。 


create_app() 函数 现在 接受 一 个 配置 类 作为 参数 。 默认 情况 下 ， 使 用 在 comfjg.py 中 定义 
的 config 类 ， 但 现在 我 可 以 通过 将 新 类 传递 给 工厂 函数 来 创建 使 用 不 同 配置 的 应 用 实例 。 下 
面 是 一 个 适用 于 我 的 单元 测试 的 示例 配置 类 : 


tests.py : 测试 配置 。 


from config import Config 


class TestConfig(Config): 
TESTING = True 
SQLALCHEMY_DATABASE_URI = 'sqlite://' 


我 在 这 里 做 的 是 创建 应 用 的 config 类 的 子 类 ， 并 覆盖 SQLAIchemy 配 置 以 使 用 内 存 SQLite 数 
据 库 。 我 还 添加 了 一 个 TESTING 属性 ， 并 设置 为 True ， 我 目前 不 需要 该 属性 ， 但 如 果 应 用 
需要 确定 它 是 否 在 单元 测试 下 运行 ， 它 就 派 上 用 场 了 。 


你 一 定 还 记得 ， 我 的 单元 测试 依赖 于 setup() 和 tearpown() 方法 ， 它 们 由 单元 测试 框架 自动 
调用 ， 以 创建 和 销毁 每 次 测试 运行 的 环境 。 我 现在 可 以 使 用 这 两 种 方法 为 每 个 测试 创建 和 销 
奴 一 个 测试 专用 的 应 用 : 


tests.py : 为 每 次 测试 创建 一 个 应 用 。 


class UserModelCase(unittest.TestCase): 
def setUp(self): 
self.app = create_app(TestConfig) 
self.app_context = self.app.app_context() 
self .app_context.push() 
db.create_all() 


def tearDown(self): 
db.session.remove() 
db.drop_all() 
self .app_context.pop() 


新 的 应 用 将 存储 在 self.app 中 ， 但 光 是 创建 一 个 应 用 不 足以 使 所 有 的 工作 者 成功。 思考 创建 
数据 库 表 的 db.create_all() 语句 。 db 实例 需要 注册 到 应 用 实例 ， 因 为 它 需 要 

从 app.config 获取 数据 库 URI， 但 是 当 你 使 用 应 用 工厂 时 ， 应 用 就 不 止 一 个 了 。 那么 db 如 
何 关联 到 我 刚刚 创建 的 self.app 实例 呢 ? 


Je 


& & Z application context? ° 还 记得 current_app REY? 当 不 存在 全 局 应 用 实例 导入 时 ， 

该 变量 以 代理 的 形式 来 引用 应 用 实例 。 这 个 变量 在 当前 线程 中 查找 活跃 的 应 用 上 下 文 ， 如 果 
找到 了 ， 它 会 从 中 获取 应 用 实例 。 如 果 没 有 上 下 文 ， 那 么 就 没有 办 法 知道 哪个 应 用 实例 处 于 
活跃 状态 ， 所 以 current_app 就 会 引发 一 个 异常 。 下 面 你 可 以 看 到 它 是 如 何在 Python 控制 台 

中 工作 的 。 这 需要 通过 运行 python 启动 ， 因 为 flask shell 命令 会 自动 激活 应 用 程序 上 下 文 
以 方便 使 用 。 


>>> from flask import current_app 
>>> current_app.config[ 'SQLALCHEMY_DATABASE_URI' ] 
Traceback (most recent call last): 


RuntimeError: Working outside of application context. 


>>> from app import create_app 

>>> app = create_app() 

>>> app.app_context().push() 

>>> current_app.config[ 'SQLALCHEMY_DATABASE_URI' ] 
"sqlite:////home/miguel/microblog/app.db' 


这 就 是 秘密 所 在 ! 在 调用 你 的 视图 函数 之 前 ，Flask 推 送 一 个 应 用 上 下 文 ， 它 会 

使 current_app 和 g 生效 。 当 请 求 完 成 时 ， 上 下 文 将 与 这 些 变 量 一 起 被 删除 。 为 了 

使 db.create_all() 调用 在 单元 测试 setup() 方法 中 工作 ， 我 为 刚刚 创建 的 应 用 程序 实例 推送 
了 一 个 应 用 上 下 文 ， 这 样 db.create_all() 可 以 使 用 current_app.config 知道 数据 库 在 哪里 。 
然后 在 teardown() 方法 中 ， 我 弹出 上 下 文 以 将 所 有 内 容重 置 为 干净 状态 。 


你 还 应 该 知道 ， 应 用 上 下 文 是 Flask 使 用 的 两 种 上 下 文 之 一 ， 还 有 一 个 请 求 上 下 文 ， 它 更 具 
体 ， 因 为 它 适 用 于 请 求 。 在 处 理 请 求 之 前 激活 请 求 上 下 文 时 ，Flask 的 request > session 以 
及 Flask-Login 的 current_user 变量 才 会 变 成 可 用 状态 。 


环境 变量 


正如 构建 此 应 用 时 你 所 看 到 的 ， 在 启动 服务 器 之 前 ， 有 许多 配置 选项 取决 于 在 环境 中 设置 的 
变量 。 这 包括 密 钥 、 电 子 邮 件 服务 器 信息 、 数 据 库 URL 和 Microsoft Translator API key。 你 
可 能 会 和 我 一 样 觉得 ， 这 很 不 方便 ， 因 为 每 次 打开 新 的 终端 会 话 时 ， 都 需要 重新 设置 这 些 变 


a 
o 


里 


译 者 注 : 可 以 通过 将 环境 变量 设置 到 开机 局 动 中 ， 来 保持 它们 在 该 计算 机 中 的 所 有 终端 
中 都 生效 。 


应 用 依赖 大 量 环境 变量 的 常见 处 理 模 式 是 将 这 些 变量 存储 在 应 用 根 目录 中 的 .emv 文 件 中 。 应 
用 在 启动 时 会 从 此 文件 中 导入 变量 ， 这 样 就 不 需要 你 手动 设置 这 些 变量 了 。 


有 一 个 支持 .env 文 件 的 Python 包 ， 名 为 python-dotenv 。 所 以 让 我 们 安装 这 个 包 : 


(venv) $ pip install python-dotenv 


由 于 config.py 模 块 是 我 读 取 所 有 环境 变量 的 地 方 ， 因 此 我 将 在 创建 Config 类 之 前 导入 .env 文 
件 ， 以 便 在 构造 类 时 设置 变量 : 


E 


config.py : 导入 .env 文 件 中 的 环境 变量 。 


import os 
from dotenv import load_dotenv 


basedir = os.path.abspath(os.path.dirname(__file__)) 
load_dotenv(os.path.join(basedir, '.env')) 


class Config(object): 
# i... 


现在 你 可 以 创建 一 个 .env 文 件 并 在 其 中 写 入 应 用 所 需 的 所 有 环境 变量 了 。 不 要 将 .env 文 件 加 入 
到 源 代码 版 本 控制 中 ， 这 非常 重要 。 否 则 ， 一 旦 你 的 密码 和 其 他 重要 信息 上 传 到 远程 代码 库 
中 后 ， 你 就 会 后 悔 英 及 。 


.EnV 文件 可 以 用 于 所 有 配置 变量 ， 但 是 不 能 用 于 Flask 命 令 行 的 FLASK_APP 和 FLASK_DEBUG 环 
境 变 量 ， 因 为 它们 在 应 用 启动 的 早期 (应 用 实例 和 配置 对 象 存 在 之 前 ) 就 被 使 用 了 。 


以 下 示例 显示 了 .emv 文 件 ， 该 文件 定义 了 一 个 安全 密 钥 ， 将 电子 邮件 配置 为 在 本 地 运行 的 邮件 
服务 器 的 25 端 口上 ， 并 且 不 进行 身份 验证 ， 设 置 Microsoft Translator API key， 使 用 数据 库 配 
置 的 默认 值 : 


SECRET_KEY=a-really-long-and-unique-key-that-nobody-knows 
MAIL_SERVER=localhost 

MAIL_PORT=25 

MS_TRANSLATOR_KEY=<your-translator -key-here> 


依赖 文件 
此 时 我 已 经 在 Python 虚拟 环境 中 安装 了 一 定数 量 的 软件 包 。 如 果 你 需要 在 另 一 台 机 器 上 重新 
生成 你 的 环境 ， 将 无 法 记 住 你 必须 安装 哪些 软件 包 ， 所 以 一 般 公 认 的 做 法 是 在 项 目的 根 目录 


中 写 一 个 reguirements.txt 文 件 ， 列 出 所 有 依赖 的 包 及 其 版 本 。 生成 这 个 列表 实际 上 很 简单 : 


(venv) $ pip freeze > requirements.txt 


pip freeze 命令 将 安装 在 虚拟 环境 中 的 所 有 软件 包 以 正确 的 格式 输入 到 requirements.txt 文 件 
尔 需 要 在 另 一 台 计 和 草 机 上 创建 相同 的 虚拟 环境 ， 无 需 逐 个 安装 软件 包 ， 可 以 


(venv) $ pip install -r requirements.txt 


本 文 翻 译 自 The Flask Mega-Tutorial Part XVI: Full-Text Search 
这 是 Flask Mega-Tutorial 系 列 的 第 十 六 部 分 ， 我 将 在 其 中 为 Microblog 添 加 全 文 搜索 功能 。 


本 章 的 目标 是 为 Microblog 实 现 搜索 功能 ， 以 便 用 户 可 以 使 用 自然 语言 查找 有 趣 的 用 户 动态 内 
容 。 许 多 不 同类 型 的 网 站 ， 都 可 以 使 用 Google，Bing 等 搜索 引擎 来 索引 所 有 内 容 ， 并 通过 其 
搜索 API 提 供 搜 索 结 果 。 这 这 方法 适用 于 静态 页 面 较 多 的 的 大 部 分 网 站 ， 比 如 论坛 。 但 在 我 
的 应 用 中 ， 基 本 的 内 容 单元 是 一 条 用 户 动态 ， 它 是 整个 网 页 的 很 小 一 部 分 。 我 想 要 的 搜索 结 
果 的 类 型 是 针对 这 些 单独 的 用 户 动态 而 不 是 整个 页 面 。 例 如 ， 如 果 我 搜索 单词 “dog”， 我 想 查 
看 任何 用 户 发 表 的 包含 该 单词 的 动态 。 很 明显 ， 显 示 所 有 包含 “dog”( 或 任何 其 他 可 能 的 搜索 
字 词 ) 的 用 户 动态 的 页 面 并 不 存在 ， 大 型 搜索 引擎 也 就 无 法 索引 到 它 。 所 以 ， 我 别 无 选择 ， 
只 能 自己 实现 搜索 功能 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


全 文 搜索 引擎 简介 


对 于 全 文 搜索 的 支持 不 像 关 系数 据 库 那样 是 标准 化 的 。 有 几 种 开源 的 全 文 搜索 四 

% : Elasticsearch > Apache Solr，Whoosh，Xapian，Sphinx 等 等 ， 如 果 这 还 不 够 ， 常 用 的 
数据 库 也 可 以 像 我 上 面 列举 的 那些 专用 搜索 引擎 一 样 提供 搜索 服务 。 SQLite，MySQL 和 
PostgreSQL 都 提供 了 对 搜索 文本 的 支持 ， 以 及 MongoDB 和 CouchDB 等 NoSQL 数 据 库 当 然 也 
提供 这 样 的 功能 。 


， 那么 答案 就 是 所 有 ! 这 是 Flask 的 强项 


如 果 你 想 知道 哪些 应 用 程序 可 以 在 Flask 应 用 中 运 
么 到 底 选 择 哪 一 个 呢 ? 


之 一 ， 它 在 完成 工作 的 同时 不 会 自作 主张 。 A 


行 

至 
专用 搜索 引擎 列表 中 ，Elasticsearch 非 常 流行 ， 部 分 原因 是 它 在 ELK 栈 中 是 用 于 索引 日 志 

和 E”， 另 两 个 是 Logstash 和 Kibana。 使 用 某 个 关系 数据 库 的 搜索 能 力也 是 一 个 不 错 的 选择 ， 


但 考虑 ee hed 支持 这 种 功能 ， or 导 不 使 用 原始 SQL 语 句 来 处 理 搜 索 ， 否 则 就 需 
要 一 个 包 ， 它 提供 一 个 文本 搜索 的 高 级 接口 ， 并 与 SQLAIchemy 共 存 。 


基于 上 述 分 析 ， 我 将 使 用 Elasticsearch， 但 我 将 以 一 种 非常 容易 切换 到 另 一 个 搜索 引擎 的 方 
式 来 实现 所 有 文本 索引 和 搜索 功能 。 你 可 以 用 其 他 搜索 引擎 的 替代 替换 我 的 实现 ， 只 需 在 单 
个 模块 中 重 写 一 些 函 数 即 可 。 


J4 。 
3% & Elasticsearch 

有 几 种 方法 可 以 安装 Elasticsearch ， 包 括 一 键 安装 程序 ， dads 装 的 二 进 制 程序 的 
zip 包 ， 甚 至 是 Docker 镜 像 。 该 文档 有 一 个 安装 页 面 ， 其 中 包 安装 选项 的 详细 信 
息 。 如 果 你 使 用 Linux， 你 可 能 会 有 一 个 可 用 于 你 的 EE 包 。 如 果 你 使 用 的 是 Mac 并 
安装 了 Homebrew， 那 么 你 可 以 简单 地 运行 brew install elasticsearch ° 


在 计算 机 上 安装 Elasticsearch 后 ， 你 可 以 在 浏览 器 的 地 址 栏 中 输入 http://localhost:9200 来 
验证 它 是 否 正 在 运行 ， 预 期 的 返回 结果 是 JSON 格 式 的 服务 基本 信息 。 


由 于 我 使 用 Python 来 管理 Elasticsearch， 因 此 我 会 使 用 其 对 应 的 Python 客户 端 库 : 


(venv) $ pip install elasticsearch 


当然 不 要 忘记 更 新 requirements.txt 文 件 : 


(venv) $ pip freeze > requirements.txt 


Elasticsearch 人 入 门 


我 将 在 Python shell 中 为 你 展示 使 用 Elasticsearch 的 基础 知识 。 这 将 帮助 你 熟悉 这 项 服务 ， 以 
便 了 解 稍 后 将 讨论 的 实现 部 分 。 


要 建立 与 Elasticsearch 的 连接 ， 需 要 创建 一 个 Elasticsearch 类 的 实例 ， 并 将 连接 URL 作 为 参 
数 传递 : 


>>> from elasticsearch import Elasticsearch 
>>> es = Elasticsearch('http://localhost:9200') 


Elasticsearch 中 的 数据 需要 被 写 入 索引 中 。 与 关系 数据 库 不 同 ， 数 据 只 是 一 个 JSON 对 象 。 
以 下 示例 将 一 个 包含 text 字段 的 对 象 写 入 名 为 my_index 的 索引 : 


>>> es.index(index='my_index', doc_type='my_index', id=1, body={'text': 'this is a tes 


t'}) 
如 果 需 要 ， 索 引 可 以 存储 不 同类 型 的 文档 ， 在 本 处 ， 可 以 根据 不 同 的 格式 将 doc_type 参数 设 
置 为 不 同 的 值 。 我 要 将 所 有 文档 存储 为 相同 的 格式 ， 因 此 我 将 文档 类 型 设置 为 索引 名 称 。 
对 于 存储 的 每 个 文档 ，Elasticsearch 使 用 了 一 个 唯一 的 ID 来 索引 含有 数据 的 JSON 对 象 。 


让 我 们 在 这 个 索引 上 存储 第 二 个 文档 : 


>>> es.index(index='my_index', doc_type='my_index', id=2, body={'text': 'a second test 


'}) 


现在 ， 该 索引 中 有 两 个 文档 ， 我 可 以 发 布 自由 格式 的 搜索 。 在 本 例 中 ， 我 要 搜 


索 this test 


>>> es.search(index='my_index', doc_type='my_index', 
. body={'query': {'match': {'text': 'this test'}}}) 


来 自 es.search() 调用 的 响应 是 一 个 包含 搜索 结果 的 Python 字典 : 


{ 
EOoOK 1, 
'timed out': False, 
'_shards': {'total': 5, 'successful': 5, 'skipped': ©, 'failed': 0}, 
"hits': { 
totalt: 27 
'max_score': 0.5753642, 
Intcsan (i 
{ 
"_index': 'my_index', 
"_type': 'my_index', 
sige) vai. 
'_score': 0.5753642, 
'_source': {'text': 'this is a test'} 
}, 
{ 
"_index': 'my_index', 
"_type': 'my_index', 
Valle Vue 
'_score': 0.25316024, 
"_source': {'text': 'a second test'} 
} 
] 
} 
} 


ep enn SA te 高 的 文档 
包含 我 搜索 的 两 个 单词 ， 而 另 一 个 文档 只 包含 一 个 单词 。 你 可 以 看 到 ， 即 使 是 最 好 的 结果 的 
分 数 也 不 是 很 高 ， 因 为 这 gn 一 致 的 。 


现在 ， 如 果 我 搜索 单词 second ， 结 果 如 下 : 


>>> es.search(index='my_index', doc_type='my_index', 
. body={'query': {'match': {'text': 'second'}}}) 


{ 
'took': 1, 
'timed_out': False, 
'"_shards': {'total': 5, 'successful': 5, 'skipped': 0, 'failed': 0}, 
Heste sf 
"total': 4, 
"max_score': 0.25316024, 
"hits': [ 
{ 
'_index': 'my_index', 
"_type': 'my_index', 
O RENAA 
'_score': 0.25316024, 
'_source': {'text': 'a second test'} 
} 
] 
} 
} 


我 仍然 得 到 相当 低 的 分 数 ， 因 为 我 的 搜索 与 文档 中 的 文本 不 匹配 ， 但 由 于 这 两 个 文档 中 只 有 
一 个 包含 “second” 这 个 词 ， 所 以 不 匹配 的 根本 不 显示 。 


Elasticsearch 查 询 对 象 有 更 多 的 选项 ， 并 且 很 好 地 进行 了 文档 化 ， 其 中 包含 诸如 分 页 和 排序 
这 样 的 和 关系 数据 库 一 样 的 功能 。 


随意 为 此 索引 添加 更 多 条 目 并 尝试 不 同 的 搜索 。 完成 试验 后 ， 可 以 使 用 以 下 命令 删除 索引 : 


>>> es.indices.delete( 'my_index' ) 


Elasticsearchiéc £ 


将 Elasticsearch 集 成 到 本 应 用 是 展现 Flask 魅 力 的 绝 佳 范例 。 这 是 一 个 与 Flask 没 有 任何 关系 
的 服务 和 Python 包 ， 然 而 ， 我 将 从 配置 开始 将 它们 恰如其分 地 集成 ， 我 先 在 app.config 模块 
中 实现 这 样 的 操作 : 


config.py : Elasticsearch 配置 。 


class Config(object): 
# i... 


ELASTICSEARCH_URL = os.environ.get( 'ELASTICSEARCH_URL' ) 


与 许多 其 他 配置 条 目 一 样 ，Elasticsearch 的 连接 URL 将 来 自 环境 变量 。 如 果 变 量 未 定义 ， 我 
将 设置 其 为 none ， 并 将 其 用 作 禁 用 Elasticsearch 的 信号 。 这 主要 是 为 了 方便 起 见 ， 所 以 当 你 
运行 应 用 时 ， 尤 其 是 在 运行 单元 测试 时 ， 不 必 强 制 Elasticsearch 服 务 启动 和 运行 。 因 此， 为 
了 确保 服务 的 可 用 性 ， 我 需要 直接 在 终端 中 定义 ELASTICSEARCH_URL 环境 变量 ， 或 者 将 它 添加 
到 env 文件 中 ， 如 下 所 示 : 


ELASTICSEARCH_URL=http://localhost :9200 


使 用 Elasticsearch 面 临 着 非 Flask 插 件 如 何 使 用 的 挑战 。 我 不 能 像 在 上 面 的 例子 中 那样 在 全 局 
范围 内 创建 Elasticsearch 实 例 ， 因 为 要 初始 化 它 ， 我 需要 访问 app.config ， 它 必须 在 调 
用 create_app() he T TA 时 所 以 我 决定 在 应 用 程序 工厂 函数 中 为 app 实例 添加 一 


个 elasticsearch 属性 : 


app/_ init .py : Elasticsearch È 4] ° 


HA 
from elasticsearch import Elasticsearch 


# ..， 


def create_app(config_class=Config): 
app = Flask(__name_) 
app.config.from_object(config_class) 


# on, 
app.elasticsearch = Elasticsearch([app.config[ 'ELASTICSEARCH_URL']]) \ 
if app.config[ 'ELASTICSEARCH_URL'] else None 


为 app 实 例 添加 一 个 新 属性 可 能 看 起 来 有 点 奇怪 ， 但 是 Python 对 象 在 结构 上 并 不 严格 ， 可 以 随 
时 添加 新 属性 。 你 也 可 以 考虑 另 一 种 方法 ， 就 是 定义 一 个 从 Flask 派生 的 子 类 (可 以 
叫 microblog ) ， 然 后 在 它 的 init () 函数 中 定义 elasticsearch 属性 。 


请 留意 我 设计 的 条 件 表 达 式 ， 如 果 Elasticsearch 服 务 的 URL 在 环境 变量 中 未 定义 ， 则 赋 


值 None 给 app.elasticsearch ° 


全 文 搜索 抽象 化 


正如 我 在 本 章 的 介绍 中 所 说 的 ， 我 希望 能 够 轻松 地 从 Elasticsearch 切 换 到 其 他 搜索 引擎 ， 并 

且 我 也 不 希望 将 此 功能 专门 用 于 搜索 用 户 动态 ， 我 更 愿意 设计 一 个 可 复 用 的 解决 方案 ， 如 果 

需要 ， 我 可 以 轻松 扩展 到 其 他 模型 。 出 于 所 有 这 些 原因 ， 我 决定 将 搜索 功能 抽象 化 。 我 的 想 
法 是 以 通用 条 件 来 设计 特性 ， 所 以 不 会 假设 post 模型 是 唯一 需要 编制 索引 的 模型 ， 也 不 会 假 
设 Elasticsearch 是 唯一 选择 的 搜索 引擎 。 但 是 如 果 我 不 能 对 任何 事情 做 出 任何 假设 ， 我 是 不 

可 能 完成 这 项 工作 的 | 


我 需要 的 做 的 第 一 件 事 ， 是 找到 一 种 通用 的 方式 来 指定 哪个 模型 以 及 其 中 的 某 个 或 某 些 字段 
将 被 索引 © 我 设 定 任何 需要 索引 的 模型 都 需要 定义 一 个 __searchable__ 属性 2 它 列 出 了 需要 
包含 在 索引 中 的 字段 。 对 于 Post 模 型 来 说 ， 变 化 如 下 : 


app/models.py: 为 Post 模 型 添加 一 个 searchable “属性 。 


class Post(db.Model): 
__ searchable = ['body'] 
tia) eine 


需要 说 明 的 是 ， 这 个 模型 需要 有 body 字段 才能 被 索引 。 不 过 ， 为 了 清楚 地 确保 这 一 点 ， 我 
添加 的 这 个 searchable ”属性 只 是 一 个 变量 ， 它 没有 任何 关联 的 行为 。 它 只 会 帮助 我 以 通 
AoA Ae RI BR e 


我 将 在 app/search.py 模 块 中 编写 与 Elasticsearch 索 引 交互 的 所 有 代码 。 这 么 做 是 为 了 将 所 有 
Elasticsearch 代 码 限制 在 这 个 模块 中 。 应 用 的 其 余部 分 将 使 用 这 个 新 模块 中 的 函数 来 访问 索 
引 ， 而 不 会 直接 访问 Elasticsearch。 这 很 重要 ， 因 为 如 果 有 一 天 我 不 再 喜欢 Elasticsearch 并 
想 切 换 到 其 他 引擎 ， 我 所 需要 做 的 就 是 重 写 这 个 模块 中 的 函数 ， 而 应 用 将 继续 像 以 前 一 样 工 

作 。 

对 于 本 应 用 ， 我 需要 三 个 与 文本 索引 相关 的 支持 功能 : 我 需要 将 条 目 添加 到 全 文 索引 中 ， 我 

需要 从 索引 中 删除 条 目 (假设 有 一 天 我 会 支持 删除 用 户 动态 ) ， 还 有 就 是 我 需要 执行 搜索 查 

询 。 下 面 是 app/search.py 模 块 ， 它 使 用 我 在 Python 控 制 台中 向 你 展示 的 功能 实现 


Elasticsearch 的 这 三 个 函数 : 


app/search.py: Search functions. 


from flask import current_app 


def add_to_index(index, model): 
if not current_app.elasticsearch: 
return 
payload = {} 
for field in model.__searchable_: 
payload[field] = getattr(model, field) 
current_app.elasticsearch.index(index=index, doc_type=index, id=model.id, 
body=payload) 


def remove_from_index(index, model): 
if not current_app.elasticsearch: 
return 
current_app.elasticsearch.delete(index=index, doc_type=index, id=model.id) 


def query_index(index, query, page, per_page): 
if not current_app.elasticsearch: 
return [], 0 
search = current_app.elasticsearch.search( 
index=index, doc_type=index, 
body={'query': {'multi_match': {'query': query, 'fields': ['*']}}, 
'from': (page - 1) * per_page, 'size': per_page}) 
ids = [int(hit['_id']) for hit in search['hits']['hits']] 
return ids, search['hits']['total'] 


这 些 函 数 都 是 通过 检查 app.elasticsearch LGA None 开始 的 ， 如 果 是 None ， 则 不 做 任何 事 
情 就 返回 。 当 Elasticsearch 服 务 器 未 配置 时 ， 应 用 会 在 没有 搜索 功能 的 状态 下 继续 运行 ， 不 
会 出 现任 何 错误 。 这 都 是 为 了 方便 开发 或 运行 单元 测试 。 


这 些 函 数 接受 索引 名 称 作为 参数 。 在 传递 给 Elasticsearch 的 所 有 调用 中 ， 我 不 仅 将 这 个 名 称 
用 作 索 引 名 称 ， 还 将 其 用 作文 档 类 型 ， 一 如 我 在 Python 控制 台 示 例 中 所 做 的 那样 。 


添加 和 删除 索引 条 目的 函数 将 SQLAIchemy 模 型 作为 第 二 个 参数 。 add_to_index() 函数 使 用 

我 添加 到 模型 中 的 ”searchable 变量 来 构建 插入 到 索引 中 的 文档 。 回顾 一 下 ， 

Elasticsearch 文 档 还 需要 一 个 唯一 的 标识 符 。 为 此 ， 我 使 用 SQLAIchemy 模 型 的 id 字段 ， 该 

字段 正好 是 唯一 的 。 在 SQLAIchemy 和 Elasticsearch 使 用 相同 的 id 值 在 运行 搜索 时 非常 有 

用 ， 因 为 它 允 许 我 链接 两 个 数据 库 中 的 条 目 。 我 之 前 没有 提 到 的 一 点 是 ， 如 果 你 尝试 添加 一 

个 带 有 现 有 id 的 条 目 ， 那 么 Elasticsearch 会 用 新 的 条 目 替换 哩 条 目 ， 所 以 add_to_index() 可 以 
用 于 新 建 和 修改 对 象 。 


在 remove_from_index() 中 的 es.delete() 函数 ， 我 之 前 没有 展示 过 ° 这 个 函数 删除 存储 在 给 
Z id 下 的 文档 。 下 面 是 使 用 相同 id 链接 两 个 数据 库 中 条 目的 便利 性 的 一 个 很 好 的 例子 


query_index() 函数 使 用 ne 文本 进行 搜索 ， 通 过 分 页 控件 ， 还 可 以 像 Flask- 
SQLAIchemy 结 果 那 样 对 搜索 结果 进行 分 页 。 你 已 经 从 Python 控制 台中 看 到 

了 es.search() 函数 的 示例 用 我 在 这 里 发 布 的 调用 非常 相似 ， 但 不 是 使 用 match 查询 类 
型 ， 而 是 使 用 multi_match ， 它 可 以 跨 多 个 字段 进行 搜索 。 通过 传递 * 的 字段 名 称 ， 我 告诉 
Elasticsearch 查 看 所 有 字段 ， 所 以 基本 上 我 就 是 搜索 了 整个 索引 。 这 对 于 使 该 函数 具有 通用 
性 很 有 用 ， 因 为 不 同 的 模型 在 索引 中 可 以 具有 不 同 的 字段 名 称 。 


es.search() 查询 的 body 参数 还 包含 分 页 参数 。 from 和 size 参数 控制 整个 结果 集 的 哪些 
子 集 需要 被 返回 。 Elasticsearch 没 有 像 Flask-SQLAIchemy 那 样 提供 一 个 很 好 的 Pagination 对 
象 ， 所 以 我 必须 使 用 分 页 数学 逻辑 来 计算 from 值 。 


She een e ety BPA return 语句 有 点 复杂 。 它 返 回 两 个 值 : 第 一 个 是 搜索 结果 的 id 元 
素 列 表 ， 第 二 个 是 结果 总 数 。 两 者 都 从 es.search() 函数 返回 的 Python 字典 中 获得 。 用 于 获 
， 被 称 为 列表 推导 式 ， 是 Python 语言 的 一 个 奇妙 功能 ， 它 允许 你 将 列表 从 
一 种 格式 转换 为 另 一 种 格式 。 在 本 例 ， 我 使 用 列表 推导 式 从 Elasticsearch 提 供 的 更 大 的 结果 
列表 中 提取 id 值 。 


这 样 看 起 来 是 否 太 混乱 ? 也 许 从 Python 控制 台 演 示 这 些 函 数 可 以 帮助 你 更 好 地 理解 它们 。 在 
接 下 来 的 会 话 中 ， 我 手动 将 数据 库 中 的 所 有 用 户 动态 添加 到 Elasticsearch 索 引 。 在 我 的 测试 
数据 库 中 ， 我 有 几 条 用 户 动态 中 包含 数字 "one”， “two”? “three”’ “four” 和 "five”， 因 此 我 将 其 
用 作 搜 索 查 询 。 你 可 能 需要 调整 你 的 查询 以 匹配 数据 库 的 内 容 : 


>>> from app.search import add_to_index, remove_from_index, query_index 
>>> for post in Post.query.all(): 
add_to_index('posts', post) 
>>> query_index('posts', ‘one two three four five', 1, 100) 
({15, 13, 12, 4, 14, 8, 14], 7) 
>>> query_index('posts', ‘one two three four five', 1, 3) 
ats 1s E12 7) 
>>> query_index('posts', ‘one two three four five', 2, 3) 
([4, 11, 8], 7) 
>>> query_index('posts', ‘one two three four five', 3, 3) 


([14], 7) 
我 发 出 的 查询 返回 了 七 个 结果 。 当 我 以 每 页 100 项 查询 第 1 页 时 ， 了 全 部 的 七 项 ， 但 接 
下 来 的 三 个 例子 显示 了 我 如 何以 与 Flask-SQLAIchemy 类 似 的 方式 对 结果 进行 分 页 ， 当 然 ， 结 


果 是 ID 列表 而 不 是 SQLAIchemy 对 象 。 


如 果 你 想 保 持 数 据 的 清洁 ， 可 以 在 做 实验 之 后 删除 posts 索引 : 


>>> app.elasticsearch.indices.delete('posts') 


集成 SQLAIchemy 到 搜索 


我 在 前 面 的 章节 中 给 出 的 解决 方案 是 可 行 的 ， 但 它 仍然 存在 一 些 问 题 。 最 明显 的 问题 是 结果 
是 以 数字 ID 列表 的 形式 出 现 的 。 这 非常 不 方便 ， 我 需要 SQLAIchemy 模 型 ， 以 便 我 可 以 将 它 

们 传递 给 模板 进行 泻 染 ， 并 且 我 需要 用 数据 库 中 相应 模型 替换 数字 列表 的 方法 。 第 二 个 问题 
是 ， 这 个 解决 方案 需要 应 用 在 添加 或 删除 用 户 动态 时 明确 地 发 出 对 应 的 索引 调用 ， 这 并 非 不 
可 行 ， 但 并 不 理想 ， 因 为 在 SQLAIlchemy 侧 进行 更 改 时 错过 索引 调用 的 情况 是 不 容易 被 检测 到 
的 ， 每 当 发 生 这 种 情况 时 ， 两 个 数据 库 就 会 越 来 越 不 同步 ， 并 且 你 可 能 在 一 段 时 间 内 都 不 会 
注意 到 。 更 好 的 解决 方案 是 在 SQLAIchemy 数 据 库 进行 更 改 时 自动 触发 这 些 调用 。 


用 对 象 替 换 ID 的 问题 可 以 通过 创建 一 个 从 数据 库 读 取 这 些 对 系 的 SQLAIchemy 得 查询 来 解决 。 
这 在 实践 中 听 起 来 很 容易 ， oe NA RA RIUE LE LILA ARF © 


对 于 自动 触发 索引 更 改 的 问题 ， 我 决定 用 SQLAIchemy 事件 驱动 Elasticsearch 索 引 的 更 新 。 
SQLAIchemy 提 供 了 大 量 的 事件 ， 可 以 通知 应 用 程序 。 例如 ， 每 次 提交 会 话 时 ， 我 都 可 以 定 
义 一 个 由 SQLAIchemy 调 用 的 函数 ， 并 且 在 该 函数 中 ， 我 可 以 将 SQLAIchemy 会 话 中 的 更 新 应 
用 于 Elasticsearch 索 引 。 


为 了 实现 这 两 个 问题 的 解决 方案 ， 我 将 编写 mixin 类 。 记得 mixin 类 吗 ? 在 第 五 章 中 ， 我 将 
Flask-Login 中 的 UserMixin 类 添加 到 了 user 模型 ， 为 它 提供 Flask-Login 所 需 的 一 些 功 能 。 对 
于 搜索 支持 ， 我 将 定义 我 自己 的 searchableMixin 类 ， 当 它 被 添加 到 模型 时 ， 可 以 自动 管理 与 
SQLAIchemy 模 型 关联 的 全 文 索引 。 mixin 类 将 充当 SQLAIchemy 和 Elasticsearch 世 界 之 间 
的 “ 粘 合 " 层 ， 为 我 上 面 提 到 的 两 个 问题 提供 解决 方案 。 


让 我 先 告诉 你 实现 ， 然 后 后 再 来 回顾 一 些 有 趣 的 细节 。 请 注意 ， 这 使 用 了 多 种 先进 技术 ， 因 此 
你 需要 仔细 研究 此 代码 以 充分 理解 它 


app/models.py : SearchableMixin 类 。 


from app.search import add_to_index, remove_from_index, query_index 


class SearchableMixin(object): 
@classmethod 
def search(cls, expression, page, per_page): 
ids, total = query_index(cls.__tablename__, expression, page, per_page) 
if total == 0: 
return cls.query.filter_by(id=0), 0 
when = [] 
for i in range(len(ids)): 
when.append((ids[i], i)) 
return cls.query.filter(cls.id.in_(ids) ).order_by( 
db.case(when, value=cls.id)), total 


@classmethod 
def before_commit(cls, session): 
session. changes = { 
‘add': [obj for obj in session.new if isinstance(obj, cls)], 
‘update': [obj for obj in session.dirty if isinstance(obj, cls)], 
‘delete': [obj for obj in session.deleted if isinstance(obj, cls)] 


} 


@classmethod 
def after_commit(cls, session): 
for obj in session._changes['add']: 
add_to_index(cls.__tablename__, obj) 
for obj in session._changes['update']: 
add_to_index(cls.__tablename__, obj) 
for obj in session._changes['delete']: 
remove_from_index(cls.__tablename__, obj) 
session. changes = None 


@classmethod 
def reindex(cls): 
for obj in cls.query: 
add_to_index(cls.__tablename__, obj) 


这 个 mixin 类 有 四 个 函数 ， 都 是 类 方法 。 复 习 一 下 ， 类 方法 是 与 类 相关 联 的 特殊 方法 ， 而 不 是 
实例 的 。 请 注意 ， 我 将 常规 实例 方法 中 使 用 的 self 参数 重 命名 为 cls ， 以 明确 此 方法 接收 
的 是 类 而 不 是 实例 作为 其 第 一 个 参数 。 例如 ， 一 旦 连接 到 post 模型 ， 上 面 的 search) 方法 
将 被 调用 为 Post.search() ， 而 不 必 将 其 实例 化 。 


search() 类 方法 封装 来 自 app/search.py 的 query_index() 函数 以 将 对 象 ID 列 表 替 换 成 实例 对 
象 。 你 可 以 看 到 这 个 函数 做 的 第 一 件 事 就 是 调用 query_index() ? 并 传 

Ù cls . tablename 作为 索引 名 称 。 这 将 是 一 个 约定 ， 所 有 索引 都 将 用 Flask-SQLAIchemy 
模型 关联 的 表 名 。 该 函数 返回 结果 |D 列 表 和 结果 总 数 。 通 过 它们 的 |D 检 索 对 象 列 表 的 
SQLAIchemy 查 询 基 于 SQL 语 言 的 case 语句 ， 该 语句 需要 用 于 确保 数据 库 中 的 结果 与 给 定 ID 
的 顺序 相同 。 这 很 重要 ， 因 为 Elasticsearch 查 询 返 回 的 结果 不 是 有 序 的 。 如 果 你 想 了 解 更 多 
关于 这 个 查询 的 工作 方式 ， 你 可 以 参考 这 个 StackOverflow 问 题 的 接受 答案 。 search() BAR 
回 替换 ID 列表 的 查询 结果 集 ， 以 及 搜索 结果 的 总 数 。 


before_commit() 和 after_commit() 方法 分 别 对 应 来 自 SQLAIchemy 的 两 个 事件 ， 这 两 个 事件 
分 别 在 提交 发 生 之 前 和 之 后 触发 。 前 置 处 理 功能 很 有 用 ， 因 为 会 话 还 没有 提交 ， 所 以 我 可 以 
查看 并 找 出 将 要 添加 ， 修 改 和 删除 的 对 象 ， 

如 session.new ， session.dirty 和 session.deleted ° 这 些 对 象 在 会 话 提交 后 不 再 可 用 ， 所 
以 我 需要 在 提交 之 前 保存 它们 。 我 使 用 session._changes 字典 将 这 些 对 象 写 入 会 话 提交 后 仍 
然 存在 的 地 方 ， 因 为 一 旦 会 话 被 提交 ， 我 将 使 用 它们 来 更 新 Elasticsearch 索 引 。 


当 调 用 after_commit() 处 理 程序 时 ， 会 话 已 成 功 提交 ， 因 此 这 是 在 Elasticsearch 端 进行 更 新 
的 适当 时 间 。 session 对 象 具有 before_commit() 中 添加 的 _changes 变 量 ， 所 以 现在 我 可 以 迭 
代 需 要 被 添加 ， 修 改 和 删除 的 对 象 ， 并 对 app/search.py 中 的 索引 元 数 进行 相应 的 调用 。 


reindex() 类 方法 是 一 个 简单 的 帮助 方法 ， 你 可 以 使 用 它 来 刷新 所 有 数据 的 索引 。 你 看 到 我 
在 上 面 做 的 将 所 有 用 户 动 态 初始 加 载 到 测试 索引 中 ， 这 个 操作 与 Python shell 会 话 中 的 类 似 。 
有 了 这 个 方法 ， 我 可 以 调用 Post.reindex() 将 数据 库 中 的 所 有 用 户 动态 添加 到 搜索 索引 中 。 


为 了 将 SearchableMixin 类 整合 到 Post 模型 中 我 必须 将 它 作 为 Post 的 基 类 并 且 还 需要 
监听 提交 之 前 和 之 后 的 事件 : 


app/models.py : 添加 SearchableMixin 类 到 Post 模 型 。 


class Post(SearchableMixin, db.Model): 
# ... 


db.event.listen(db.session, 'before_commit', Post.before_commit ) 
db.event.listen(db.session, 'after_commit', Post.after_commit ) 


请 注意 ” db.event.listen() 调用 不 在 类 内 部 2 而 是 在 其 后 面 这 两 行 代码 设置 了 每 次 提交 之 
前 和 之 后 调用 的 事件 处 理 程序 。 现在 post 模型 会 自动 为 用 户 动态 维护 一 个 全 文 搜索 索引 。 
我 可 以 使 用 reindex() 方法 来 初始 化 当前 在 数据 库 中 的 所 有 用 户 动 态 的 索引 : 


>>> Post.reindex() 


我 可 以 通过 运行 post.search() 来 搜索 使 用 SQLAIchemy 模 型 的 用 户 动态 。 在 下 面 的 例子 中 ， 
我 要 求 查询 第 一 页 的 五 个 元 素 : 


>>> query, total = Post.search('one two three four five', 1, 5) 
>>> total 

7 

>>> query.all() 

[<Post five>, <Post two>, <Post one>, <Post one more>, <Post one>] 


搜索 表单 


的 确 有 些 激进 。 我 上 面 做 的 保持 通用 性 的 工作 涉及 到 几 个 高 级 主题 ， 因 此 可 能 需要 一 些 时 间 
能 完全 理解 。 现 在 我 有 一 套 完 整 的 系统 来 处 理 用 户 动态 的 自然 语言 搜索 。 所 以 现在 需要 做 
的 是 将 所 有 这 些 功能 与 应 用 集成 在 一 起 。 


基于 网 络 搜索 的 一 种 相当 标准 的 方法 是 在 URL 的 查询 字符 串 中 将 搜索 词 作 为 q FAN Bl 
如 ， 如 果 你 想 在 Google 上 搜索 python ， 并 且 想 要 节约 少许 时 间 ， 则 只 需 在 浏览 器 的 地 址 栏 中 
输入 以 下 URL 即 可 直接 查看 结果 : 


https://www.google.com/search?q=python 


允许 将 搜索 完全 封装 在 URL 中 是 很 好 的 ， 因 为 这 方便 了 与 其 他 人 共享 ， 只 要 点 击 链接 就 可 以 
访问 搜索 结果 。 


请 允许 我 向 你 介绍 一 种 区 别 于 以 前 的 Web 表 单 的 处 理 方 式 。 我 曾经 使 用 PosT 请 求 来 提交 
单数 据 ， 但 是 为 了 实现 上 述 搜索 ， 表 单 提交 必须 以 GET 请 求 发 送 ， 这 是 一 种 请 求 方法 ， 当 你 
在 浏览 器 中 输入 网 址 或 点 击 链接 时 ， 就 是 GET 请 求 。 另 一 个 有 趣 的 区 别 是 搜索 表单 将 存在 于 
导航 栏 中 ， 因 此 它 将 会 出 现 应 用 的 所 有 页 面 中 。 


这 里 是 搜索 表单 类 ， 只 有 q 文本 字段 : 
app/main/forms.py : 搜索 表单 。 


from flask import request 


class SearchForm(FlaskForm): 
q = StringField(_1l('Search'), validators=[DataRequired()]) 


def _ init__(self, *args, **kwargs): 
if 'formdata' not in kwargs: 
kwargs['formdata'] = request.args 
if 'csrf_enabled' not in kwargs: 
kwargs['csrf_enabled'] = False 
super(SearchForm, self). __init__(*args, **kwargs) 


q 字段 不 需要 任何 解释 ， 因 为 它 与 我 以 前 使 用 的 其 他 文本 字段 相似 。 在 这 个 表单 中 ， 我 不 需 
要 提交 按钮 。 对 于 具有 文本 字段 的 表单 ， 当 焦点 位 于 该 字段 上 时 ， 你 按 下 Enter 键 ， 浏 览 器 将 
提交 表单 ， 因 此 不 需要 按钮 。 我 还 添加 了 一 个 _init 构造 函数 ， 它 提供 


了 formdata 和 csrf_enabled 参数 的 值 (如 果 调 用 者 没有 提供 它们 的 话 ) 。 formdata FAR 
定 Flask-WTF 从 哪里 获取 表单 提交 。 缺 省 情况 是 使 用 request.form ， 这 是 Flask 放 置 通 

过 post 请 求 提交 的 表单 值 的 地 方 。 通 过 GET 请 求 提交 的 表单 在 查询 字符 串 中 传递 字段 值 ， 
所 以 我 需要 将 Flask-WTF 指 向 request.args ， 这 是 Flask 写 查询 字符 串 参 数 的 地 方 。 你 是 否 还 
记得 的 ， 表 单 默 认 添加 了 CSRF 保 护 ， 包 含 一 个 CSRF 标 记 ， 该 标记 通过 模板 中 

的 form.hidden_tag() 构造 添加 到 表单 中 。 为 了 使 搜索 表单 运作 ，CSRF 需 要 被 禁用 ， 所 以 我 
将 csrf_enabled 设置 为 False ， 以 便 Flask-WTF 知 道 它 需要 忽略 此 表单 的 CSRF 验 证 。 


由 于 我 需要 在 所 有 页 面 中 都 显示 此 表单 ， 因 此 无 论 用 户 在 查看 哪个 页 面 ， 我 都 需要 创建 一 
个 searchForm 类 的 实例 。 唯一 的 要 求 是 用 户 登 录 ， 因 为 对 于 匿名 用 户 ， 我 目前 不 会 显示 任何 
内 容 。 与 其 在 每 个 路 由 中 创建 表单 对 象 ， 然 后 将 表单 传递 给 所 有 模板 ， 我 将 向 你 展示 一 个 非 
常 有 用 的 技巧 ， 当 你 需要 在 整个 应 用 中 实现 一 个 功能 时 ， 可 以 消除 重复 代码 。 回 到 第 六 章 ， 
我 已 经 使 用 了 before_request 处 理 程序 ， 来 记录 每 个 用 户 上 次 访问 的 时 间 。 我 要 做 的 是 在 同 
样 的 功能 中 创建 我 的 搜索 表单 ， 但 有 一 点 区 别 : 


app/main/routes.py : 在 请 求 处 理 前 的 处 理 器 中 初始 化 搜索 表单 。 


from flask import g 
from app.main.forms import SearchForm 


@bp.before_app_request 
def before_request(): 
if current_user.is_authenticated: 
current_user.last_seen = datetime.utcnow() 
db.session.commit() 
g.search_form = SearchForm() 
g.locale = str(get_locale()) 


在 这 里 ， 当 用 户 已 认证 时 ， 我 会 创建 一 个 搜索 表单 类 的 实例 。 当 然 ， 我 需要 这 个 表单 对 象 一 
直 存 在 ， 直 到 它 可 以 在 请 求 结束 时 浑 染 ， 所 以 我 需要 将 它 存储 在 某 个 地 方 。 那 个 地 方 就 是 
Flask 提 供 的 g 容器 。 这 个 g 变量 是 应 用 可 以 存储 需要 在 整个 请 求 期 间 持 续 存 在 的 数据 的 地 
方 。 在 这 里 ， 我 将 表单 存储 在 g.search_form 中 ， 所 以 当 请 求 前 置 处 理 程序 结束 并 且 Flask 调 
Was 对 象 将 会 是 相同 的 ， 并 且 表 单 仍 然 存在 。 请 注意 ， 这 
个 g 变量 对 每 个 请 求 和 每 个 客户 端 都 是 特定 的 ， 因 此 即使 你 的 Web 服 务 器 一 次 为 不 同 的 客户 
o: 个 请 求 ， 仍 然 可 以 依靠 g 来 专用 存储 各 个 请 求 的 对 应 变量 。 


下 一 步 是 将 表单 演 染 成 页 面 。 is sap a fae Senne 个 表单 ， 所 以 更 有 意 
义 的 是 将 其 作为 导航 栏 的 一 部 分 进行 泻 染 。 事实 上 ， 这 很 简单 ， 因 为 模板 也 可 以 看 到 存储 
fig 变量 中 的 数据 ， 所 以 我 不 需要 在 所 有 render_template() 调用 中 将 表单 作为 显 式 模板 参数 
添加 进去 。 以 下 是 我 如 何在 基础 模板 中 泻 染 表单 的 代码 : 


app/templates/base.html : 在 导航 栏 中 泻 染 搜索 表单 。 


<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> 
<ul class="nav navbar-nav"> 
. home and explore links ... 
</ul> 
{% if g.search_form %} 
<form class="navbar-form navbar-left" method="get" 
action="{{ url_for('main.search') }}"> 
<div class="form-group"> 
{{ g.search_form.q(size=20, class='form-control', 
placeholder=g.search_form.q.label.text) }} 
</div> 
</form> 
{% endif %} 


只 有 在 定义 了 g.search_form 时 才 会 泻 染 表 单 2 此 检查 是 必要 的 ， 因为 某 些 页 面 (如 错误 页 
面 ) 可 能 没有 定义 它 9 这 个 表单 与 我 之 前 做 过 的 略 有 不 同 所 我 将 method 属性 设置 为 get ， 
因为 我 希望 表单 数据 作为 查询 字符 串 ， 通 过 GET 请 求 提交 。 另外 ， 我 创建 的 其 他 表 

单 actin 属性 为 室 ， 因 为 它们 被 提交 到 浑 染 表 单 的 同一 页 面 。 而 这 个 表单 很 特殊 ， 因 为 它 出 
现在 所 有 页 面 中 ， 所 以 我 需要 明确 告诉 它 需要 提交 的 地 方 ， 这 是 专门 用 于 处 理 搜索 的 新 路 
由 。 


搜索 视图 函数 


完成 搜索 功能 的 最 后 一 项 功能 是 接收 搜索 表单 的 视图 防 数 。 该 视图 函数 将 被 附加 到 /search 路 
由 ， 以 便 你 可 以 发 送 类 似 http:/Nlocalhost:5000/search?q=search-words 的 搜索 请 求 ， 就 像 
Google 一 样 。 


app/main/routes.py : 搜索 视图 函数 。 


@bp.route('/search' ) 
@login_required 
def search(): 
if not g.search_form.validate(): 
return redirect(url_for('main.explore' )) 
page = request.args.get('page', 1, type=int) 
posts, total = Post.search(g.search_form.q.data, page, 
current_app.config[ 'POSTS_PER_PAGE']) 
next_url = url_for('main.search', q=g.search_form.q.data, page=page + 1) \ 
if total > page * current_app.config['POSTS_PER_PAGE'] else None 
prev_url = url_for('main.search', q=g.search_form.q.data, page=page - 1) \ 
if page > 1 else None 
return render_template('search.html', title=_('Search'), posts=posts, 
next_url=next_url, prev_url=prev_ur1) 


你 已 经 看 到 ， 在 其 他 表单 中 ， 我 使 用 form. validate_on _submit() 方法 来 检查 表单 提交 是 否 有 
效 。 不 幸 的 是 ， 该 方法 只 适用 于 通过 post 请 求 提交 的 表单 ， 所 以 对 于 这 个 表单 ， ee 
用 form. Ae ， 它 只 验证 字段 值 ， 而 不 检查 数据 是 如 何 提交 的 。 如 果 验 证 失败 ， 这 是 因 
为 用 户 提交 空 的 搜索 表单 ， 所 以 在 这 种 情况 下 ， 我 只 能 重 定向 到 ie von 
的 发 现 页 面 


Searchablemixin 类 中 的 post.search() 方法 用 于 获取 搜索 结果 列表 。 分 页 的 处 理 方式 与 主页 
和 发 现 页 面 非常 类 似 ， 但 如 果 没 有 Flask-SQLAIchemy 的 “分 页 ”对象 的 帮助 ， 生 成 下 一 个 和 前 
一 个 链接 会 有 点 糠 手 。 这 是 从 post.search() 返回 的 结果 总 数 的 用 途 所 在 。 


一 旦 计算 出 搜索 结果 和 分 页 链接 的 页 面 ， 剩 下 的 就 是 泻 染 一 个 包含 所 有 这 些 数据 的 模板 。 我 
已 经 想 出 了 一 种 重用 jindex.html 模 板 来 显示 搜索 结果 的 方法 ， 但 考虑 到 有 一 些 差 异 ， 我 决定 创 
建 一 个 专用 于 显示 搜索 结果 的 search.html 专 属 模 板 ， 以 _post.html 子 模板 的 优势 来 演 染 搜索 
结果 : 


app/templates/search.html : 搜索 结果 模板 。 


{% extends "base.html" %} 


{% block app_content %} 
<hi>{{ _('Search Results') }}</h1> 
{% for post in posts %} 
{% include '_post.html' %} 
{% endfor %} 
<nav aria-label="..."> 
<ul class="pager"> 
<li class="previous{% if not prev_url %} disabled{% endif %}"> 
<a href="{{ prev_url or '#' }}"> 
<span aria-hidden="true">&larr; </span> 
{{ _('Previous results') }} 
</a> 
</li> 
<li class="next{% if not next_url %} disabled{% endif %}"> 
<a href="{{ next_url or '#' }}"> 
{{ _('Next results') }} 
<span aria-hidden="true">&rarr; </span> 
</a> 
</li> 
</ul> 
</nav> 
{% endblock %} 


如 果 前 一 个 和 下 一 个 链接 的 泻 染 逻辑 有 点 混乱 ， 可 能 查看 分 页 组 件 的 Bootstrap 文 档 会 有 所 帮 
助 。 


Search - Microblog 


< GC QQ © localhost:5000/search?q=o 
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感想 如 何 ? 本 章 的 内 容 有 些 激进 ， 因 为 里 面 介 绍 了 一 些 相 当先 进 的 技术 。 本 章 中 的 一 些 概念 
可 能 需要 你 花 一 些 时 间 才 能 有 所 领悟 。 本 章 | 
不 同 的 搜索 引擎 ， 只 需要 重 写 app/search.py 即 可 。 这 项 工作 的 另 一 个 重要 好 处 是 ， 如 果 
我 需要 为 另外 的 数据 库 模 型 添加 搜索 支持 ， 我 可 以 简 e 过 向 它 添加 searchablemixin 类 ， 
为 _searchable ”属性 填写 要 索引 的 字段 列表 和 SQLAIlchemy 事 件 处 理 程序 的 监听 即 可 。 我 
认为 这 些 努 力 是 值得 的 ， 因 为 从 现在 起 ， 处 理 全 文 索 引 将 会 变 得 十 分 容易 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part XVII: Deployment on Linux 
这 是 Flask Mega-Tutorial 系 列 的 第 十 七 部 分 ， 我 将 把 Microblog 部 署 到 Linux 服 务 器 。 


在 本 章 中 ， 我 将 谈 到 Microblog 应 用 生命 周期 中 的 一 个 里 程 碑 ， 因 为 我 将 讨论 如 何 将 应 用 部 署 
到 生产 服务 器 上 ， 以 便 站 实 用 户 可 以 访问 它 。 


部 署 的 主题 非常 广泛 ， 因 此 不 可 能 在 这 里 涵盖 所 有 范畴 。 本 章 致 力 于 探讨 传统 托管 方式 ， 包 
括 Ubuntu 发 行 版 的 Linux 服 务 器 和 流行 的 树 医 派 微机 。 我 将 在 后 面 的 章节 中 介绍 其 他 选项 ， 例 
如 云 和 容器 部 署 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


传统 托管 


当 提 到 "传统 托管 "时 ， 意 思 是 应 用 是 手动 或 通过 原始 服务 器 机 器 上 的 脚本 安装 部 署 的 。 该 过 
程 涉及 安装 应 用 程序 、 其 依赖 项 和 生产 规模 的 Web 服 务 器 ， 并 配置 系统 以 确保 其 安全 。 


当 你 要 部 署 自己 的 项 目 时 ， 要 问 的 第 一 个 问题 是 在 哪 找 服 务 器 。 目前 有 很 多 经 济 的 托管 服 
务 。 只 需 每 月 5 美元 ，Digital Ocean，Linode 或 Amazon Lightsail 就 可 以 租借 一 台 虚 拟 化 Linux 
服务 器 (Linode 和 Digital Ocean 为 其 入 门 级 服务 器 提供 1GB RAM， 而 亚马逊 仅 提 供 512MB ) 
给 你 运行 部 署 实 验 。 如 果 你 一 分 钱 都 不 愿意 花 ， 那 么 Vagrant 和 VirtualBox 组 合 而 成 的 工具 ， 
可 以 让 你 在 自己 的 计算 机 上 创建 一 个 与 付费 服务 器 类 似 的 庶 拟 服务 器 。 


就 技术 角度 而 言 ， 该 应 用 可 以 部 署 在 任何 主流 操作 系统 上 ， 包 括 各 种 开放 源 代 码 的 Linux 和 
BSD 发 行 版 以 及 商用 的 OS X (OS X 是 一 个 开源 和 商业 的 混 种 ， 因 为 它 基 于 开源 BSD 衍 生产 品 
Darwin) 和 Microsoft Windows 。 


由 于 OS X 和 Windows 是 的 桌面 操作 系统 ， 不 是 作为 服务 器 的 最 佳 选 择 ， 因 此 不 是 首选 。 
Linux 或 BSD 操 作 系 统 之 间 的 选择 很 大 程度 上 取决 于 爱好 ， 所 以 我 将 选择 其 中 更 受 
Linux 。 而 Linux 发 行 版 中 ， 我 将 再 次 选择 受 欢迎 的 Ubuntu。 


创建 Ubuntu 服务 器 


如 果 你 有 兴趣 与 我 一 起 部 署 ， 那 么 就 需要 一 台 服 务 器 才能 开始 工作 。 为 你 推荐 两 种 选择 ， 一 
种 是 付费 的 ， 另 一 种 是 免费 的 。 如 果 你 愿意 花 一 点 钱 ， 可 以 在 Digital Ocean，Linode 或 
Amazon Lightsail 上 注册 一 个 账户 ， 并 创建 一 个 Ubuntu 16.04 镜 像 的 虚拟 服务 器 。 你 应 该 使 用 
最 低 配 置 的 服务 器 ， 在 我 写 这 篇 文章 的 时 候 ， 三 家 的 最 低 配置 都 是 每 月 5 美元 。 开销 是 按照 服 
务 器 启动 的 小 时 数 进行 比例 计算 的 ， 因 此 ， 如 果 你 创建 服务 器 后 ， 使 用 几 个 小 时 然后 删除 

它 ， 那 么 有 可 能 你 只 需 支付 美 分 级 别 的 费用 。 


免费 的 方案 基于 你 的 计算 机 上 可 以 运行 虚拟 机 。 要 使 用 此 选项 ， 请 在 你 的 机 器 上 安装 Vagrant 
和 VirtualBox， 然 后 创建 一 个 名 为 Vagrantfile 的 文件 并 用 以 下 内 容 来 描述 虚拟 机 的 规格 : 


Vagrantfile : Vagrant 配 置 。 


Vagrant.configure("2") do |config| 
config.vm.box = "ubuntu/xenial64" 
config.vm.network "private_network", ip: "192.168.33.10" 
config.vm.provider "virtualbox" do |vb| 
vb.memory = "1024" 
end 
end 


该 文件 配置 了 一 个 带 有 1GB RAM 的 Ubuntu 16.04 服 务 器 ， 你 可 以 用 其 IP 地 址 192.168.33.10 来 
访问 该 服务 器 。 要 创建 服务 器 ， 请 运行 以 下 命令 : 


$ vagrant up 


请 参阅 Vagrant 命令 行文 档 了 解 其 他 管理 虚拟 服务 器 的 选项 。 


你 的 服务 器 处 于 后 端 ， 所 以 不 需要 像 个 人 计算 机 上 那样 拥有 桌面 。 你 可 以 通过 SSH 客 户 端 连 
接 到 服务 器 ， 并 运行 命令 行进 行 交 互 。 如 果 你 使 用 的 是 Linux 或 Mac OS X， 则 可 能 已 经 安装 
T OpenSSH ° 如 果 你 使 用 Microsoft Windows > Cygwin > Gitf#Windows Subsystem for 
Linux 提 供 OpenSSH， 因 此 你 可 以 安装 这 些 选项 中 的 任何 一 个 。 


如 果 你 正在 使 用 来 自 第 三 方 提供 商 的 虚拟 服务 器 ， 则 在 创建 服务 器 时 ， 会 为 其 分 配 |P 地 址 。 
你 可 以 使 用 以 下 命令 打开 终端 会 话 来 连接 到 该 服务 器 : 


$ ssh root@<server-ip-address> 


系统 会 提示 你 输入 密码 。 密 码 已 在 创建 服务 器 后 自动 生成 并 显示 给 你 ， 或 者 你 自己 指定 了 密 


如 果 你 使 用 的 是 Vagrant VM， 则 可 以 使 用 以 下 命令 打开 终端 会 话 : 


$ vagrant ssh 


如 果 你 使 用 的 是 Windows 并 且 拥 有 Vagrant 虚 拟 机 ， 请 注意 你 需要 从 可 以 调用 ssh 命令 的 shell 
运行 上 述 命令 。 


如 果 你 使 用 的 是 Vagrant 虚 拟 机 ， 那 么 可 以 跳 过 本 节 ， 因 为 你 的 虚拟 机 已 正确 配置 为 使 用 名 
为 ubuntu 的 非 root 帐 户 ，Vagrant 不 用 输入 密码 就 可 以 自动 登录 。 


要 是 你 使 用 的 是 庶 拟 服务 器 ， 则 建 一 个 常规 用 户 来 完成 你 的 部 署 工作 ， 并 配置 此 帐户 
以 便 在 不 使 用 密码 的 情况 下 登录 ， 这 么 做 最 初 看 起 来 似乎 是 一 个 糟糕 的 主意 ， 之 后 你 会 发 现 
它 不 仅 更 方便 ， 而 且 更 安全 。 


我 将 创建 一 个 名 为 ubuntu 的 用 户 帐 户 (如 果 你 愿意 ， 可 以 使 用 其 他 名 称 ) 。 要 创建 这 个 用 
户 ， 请 使 用 前 一 节 中 的 ssh 指令 登录 到 你 的 服务 器 的 root 帐 户 ， 然 后 键入 以 下 命令 来 创建 用 
户 ， 给 它 sudo 权限 并 最 终 切换 到 它 


$ adduser --gecos "" ubuntu 
$ usermod -aG sudo ubuntu 
$ su ubuntu 


现在 我 要 配置 这 个 新 的 ubuntu 帐户 来 使 用 public key 认 证 ， 以 便 你 可 以 免 密 登 录 。 


先 不 管 服务 器 上 打开 的 终端 会 话 ， 然 后 在 本 地 计算 机 上 启动 第 二 个 终端 。 如 果 你 使 用 的 是 
Windows， 这 需要 是 可 以 访问 ssh 命令 的 终端 ， 所 以 它 可 能 是 一 个 bash 或 者 类 似 的 提示 符 
的 终端 ， 而 不 是 本 地 的 Windows 终 端 。 在 该 终端 会 话 中 ， 检 查 ~/Ssh 目 录 的 内 容 : 


$ ls ~/.ssh 
id_rsa id_rsa.pub 


如 果 目 录 列 表 显 示 如 上 所 述 的 名 为 jd_rsa 和 id_rsa.pub 的 文件 ， 那 么 你 已 经 有 一 个 密 钥 。 如 果 
没有 这 两 个 文件 ， 或 者 根本 没有 ~/,ssh 目 录 ， 则 你 需要 运行 以 下 命令 (也 是 OpenSSH 工 具 集 
的 一 部 分 ) 来 创建 SSH 密 钥 对 : 


$ ssh-keygen 
此 应 用 程序 将 提示 你 输入 一 些 内 容 ， 为 此 我 建议 你 在 所 有 提示 中 按 Enter 尺 接受 默认 设置 。 你 
当然 也 可 gaat 及 置 ， 如 果 你 知道 这 么 做 意味 着 什么 的 话 。 


运行 此 命令 后 ， 应 该 有 上 面 列 出 的 两 个 文件 了 。 文件 ia_rsa.pub 是 你 的 公 钥 ， 这 是 一 个 你 将 
提供 给 第 三 方 的 文件 ， 用 于 识别 你 的 身份 。 ja_rsa 文 件 是 你 的 私 钥 ， 不 应 与 任何 人 共享 。 


你 现在 需要 将 公 钥 配置 为 服务 器 中 的 授权 主机 。 在 你 自己 的 计算 机 上 打开 的 终端 上 ， 将 公 钊 
打印 到 屏幕 上 : 


$ cat ~/.ssh/id_rsa.pub 
ssh-rsa AAAAB3NzaCiyc2EAAAADAQABAAABAQCjw....F8Xv4F/0+7WT miguel@miguelspc 


这 将 是 一 个 非常 长 的 字符 序列 ， 显 示 时 可 能 跨越 多 行 (但 实际 上 只 有 一 行 ) 。 你 需要 将 此 数 
据 复 制 到 剪贴 板 ， 然 后 切换 回 远 程 服务 器 上 的 终端 你 将 在 其 中 运行 以 下 命令 来 存储 公 和 铀 : 


$ echo <paste-your-key-here> >> ~/.ssh/authorized_keys 
$ chmod 600 ~/.ssh/authorized_keys 


免 密 登 录 现 在 应 该 可 以 工作 了 。 背后 逻辑 是 ， 你 机 器 上 的 ssh 会 用 私 铀 执行 加 密 操 作 来 向 服 
务 器 标识 自己 。 然后 服务 器 使 用 你 的 公 乌 验证 操作 是 否 有 效 。 


你 现在 可 以 注销 ubuntu 会 话 ， 然 后 注销 root 会 话 ， 然 后 尝试 直接 登录 到 ubuntu 帐户 : 


$ ssh ubuntu@<server -ip-address> 


这 一 次 不 用 输入 密码 就 登录 了 | 


保护 你 的 服务 器 
为 了 最 大 限度 地 降低 服务 器 受到 攻击 的 风险 ， 你 可 以 采取 一 些 措施 来 关闭 攻击 者 可 能 访问 的 
大 量 潜在 漏洞 。 


我 要 做 的 第 一 个 更 改 是 禁用 root 用 户 通过 SSH 登 录 。 你 现在 可 以 无 密码 地 访问 ubuntu 帐户 ， 
并 且 可 以 通过 sudo 从 该 帐户 运行 管理 员 命令 ， 因 此 实际 上 不 需要 暴露 root 帐 户 。 要 禁用 root 
登录 ， 你 需要 编辑 服务 器 上 的 /etc/ssh/sshd_config 文 件 。 你 可 能 在 你 的 服务 器 上 安装 

了 vi 和 nano 文本 编辑 器 ， 你 可 以 用 它 来 编辑 文件 (如果 你 不 熟悉 这 两 种 文件 编辑 器 ， 可 以 
首先 尝试 nano) 。 由 于 SSH 配 置 对 普通 用 户 是 不 可 访问 的 ， 所 以 你 需要 在 编辑 器 命令 前 添 
加 sudo ( 即 sudo vi /etc/ssh/sshd_config ) $ 你 需要 更 改 此 文件 中 的 单行 : 


/etc/ssh/sshd_config : 禁止 root 登 录 。 


PermitRootLogin no 
请 注意 ， 要 进行 此 更 改 ， 你 需要 找到 以 PermitRootLogin 开头 的 行 ( 找 不 到 就 新 建 一 行 ) 并 将 
该 值 更 改 为 no ° 


下 一 个 更 改 在 同一 个 文件 中 。 现在 我 要 为 所 有 帐户 禁用 密码 登录 。 你 有 一 个 无 密码 的 登录 设 
置 ， 所 以 没有 必要 允许 密码 。 如 果 你 对 完全 禁用 密码 感到 紧张 ， 可 以 跳 过 此 更 改 ， 但 对 于 生 
产 服务 器 来 说 ， 这 是 一 个 非常 好 的 主意 ， 因 为 攻击 者 经 常 在 所 有 服务 器 上 尝试 随机 帐户 名 和 
密码 并 希望 能 中 奖 。 要 禁用 密码 登录 ， 请 在 /etc/ssh/sshqd_config 中 更 改 以 下 行 : 


/etc/ssh/sshd_config : 禁用 密码 登录 。 


PasswordAuthentication no 


完成 编辑 SSH 配 置 后 ， 需 要 重新 启动 ssh 服 务 以 使 更 改 生 效 : 


$ sudo service ssh restart 


我 要 做 的 第 三 个 改变 是 安装 防火 墙 。 这 是 一 个 阻止 在 任何 未 明确 启用 的 端口 上 访问 服务 器 的 
软件 : 


sudo apt-get install -y ufw 
sudo ufw allow ssh 

sudo ufw allow http 

ufw allow 443/tcp 

sudo ufw --force enable 
sudo ufw status 
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这 些 命令 会 安装 Ufw (简单 防火 墙 ) ， 并 将 其 配置 为 仅 允 许 端口 22 (ssh) ，80 (http) 和 
e 信 。 任何 其 他 端口 将 不 被 允许 。 


安装 基础 依赖 


如 果 你 遵循 了 我 的 建议 并 配置 了 Ubuntu 16.04 发 行 版 的 服务 器 ， 那 么 你 的 系统 完全 支持 
Python 3.5， 因 此 这 是 我 将 用 于 部 署 的 Python 版 本 。 


基础 的 Python 解释 器 可 能 已 经 预先 安装 在 你 的 服务 器 上 ， 但 有 一 些 额 外 的 软件 包 可 能 却 没 

有 ， sw 可 用 于 创建 健壮 的 生产 环境 部 署 。 对 于 数据 库 服务 
器 ， 我 将 从 SQLite 切 换 到 MySQL © Postfix 包 是 一 个 邮件 传输 代理 ， 我 将 用 它 来 发 送 电子 邮 
件 。Supervisor 工 具 将 监视 Flask 服 务 器 进程 ， 并 在 其 崩溃 时 自动 重启 ， 并 当 Supervisor 服 务 
重启 后 自动 启动 其 监视 的 服务 。 Nginx 服 务 器 将 接受 来 自 外 部 世界 的 所 有 请 求 ， 并 将 它们 转发 
给 应 用 程序 。 最 后 ， 我 将 使 用 git 来 从 git 仓 库 下 载 应 用 程序 。 


$ sudo apt-get -y update 
$ sudo apt-get -y install python3 python3-venv python3-dev 
$ sudo apt-get -y install mysql-server postfix supervisor nginx git 


LERRARDRAAMTH  WRABHB2 RRR OS ARM» AMARTA 
MySQL 服 务 选择 一 个 root 密 码 ， 并 且 还 会 询问 关于 安装 postfix 软 件 包 的 一 些 问题 ， 你 可 以 接 
受 他 们 的 默认 答案 。 


请 注意 ， 对 于 此 部 署 ， 我 选择 不 安装 Elasticsearch。 这 项 服务 需要 大 量 的 RAM， 所 以 只 有 拥 
有 超过 2GB 内 存 的 大 型 服务 器 时 才 可 以 考虑 。 为 了 避免 服务 器 内 存 不 足 的 问题 ， 我 将 停 用 搜 
索 功 能 。 如果 你 有 高 配 的 服务 器 ， 可 以 从 Elasticsearch 站 点 下 载 官方 的 .deb 软 件 包 ， 并 按照 
其 安装 说 明 将 其 添加 到 你 的 服务 器 。 请 注意 ，Ubuntu 16.04 软 件 包 存储 库 中 提供 的 
Elasticsearch 软 件 包 太 上 日 ， 无 法 运行 ， 你 需要 6.X 或 更 高 版 本 。 


我 还 注意 到 ， 软 认 安 装 的 postfix 可 能 不 足以 在 生产 环境 中 发 送 电子 邮件 。 为 了 避免 垃圾 邮件 
和 恶意 邮件 ， 很 多 服务 器 都 要 求 发 件 人 服务 器 通过 安全 扩展 标识 自己 ， 这 意味 着 至 少 你 必须 
拥有 与 你 的 服务 器 相关 联 的 域名 。 如 果 你 想 了 解 如 何 完 全 配置 电子 邮件 服务 器 以 使 其 通过 标 
准 安 全 测试 ， 请 参阅 以 下 Digital Ocean 的 指南 : 


e Postfix Configuration 


e Adding an SPF Record 
e DKIM Installation and Configuration 


3c EL Fl 


现在 我 要 使 用 git 从 我 的 GitHub 代 码 库 下 载 Microblog 源 代码 。 如 果 你 不 熟悉 git 源 码 控 制 ， 
我 建议 你 阅读 git for beginners ° 


要 将 应 用 下 载 到 服务 器 ， 请 确保 你 位 于 ubuntu 用 户 的 主 目录 中 ， 然 后 运行 : 


$ git clone https://github.com/miguelgrinberg/microblog 
$ cd microblog 
$ git checkout v0.17 


文 会 将 代码 克隆 到 你 的 服务 器 上 ， 并 将 其 同步 到 本 章 的 内 容 。 如 果 你 在 学 习 本 教程 的 过 程 中 
维护 了 自己 的 git 代 码 库 ， 则 可 以 将 代码 库 URL 更 改 为 你 的 URL， 在 这 种 情况 下 ， 你 可 以 跳 


过 git checkout 命令 9 


现在 我 需要 创建 一 个 虚拟 环境 并 使 用 所 有 的 包 依赖 项 来 填充 它 ， 在 第 十 五 章 中 ， 我 已 将 依赖 
包 的 列表 保存 到 requirements.txt 文 件 中 : 


$ python3 -m venv venv 
$ source venv/bin/activate 
(venv) $ pip install -r requirements.txt 


除了 requirements.txt 中 的 包 之 外 ， 我 还 将 使 用 此 生产 部 署 指定 的 两 个 包 ， 因 此 它们 不 包 
在 requirements.txt 文 件 中 。 gunicorn 软件 包 是 Python 应 用 程序 的 生产 Web 服 务 器 。 
pymysql 软件 包 和 包含 MySQL 了 驱动 程序 ， 它 使 SQLAIchemy 能 够 与 MySQL 数 据 库 一 起 工作 : 


(venv) $ pip install gunicorn pymysql 


我 需要 创建 一 个 ,env 文件， 其 中 包含 所 有 需要 的 环境 变量 : 


/home/ubuntu/microblog/.env : 环境 配置 。 


SECRET_KEY=52cb883e323b48d78a0a36e8e951ba4a 

MAIL_SERVER=Localhost 

MAIL_PORT=25 

DATABASE_URL=mysql+pymysql://microblog:<db-password>@localhost :3306/microblog 
MS_TRANSLATOR_KEY=<your-translator -key-here> 


这 个 .env 文 件 与 我 在 第 十 五 章 展 示 的 非常 类 似 ， 但 是 我 为 SECRET_KEY 使 用 了 一 个 随机 字符 
事 。 为 了 生成 这 个 随机 字符 事 ， 我 使 用 了 下 面 的 命令 


python3 -c "import uuid; print(uuid.uuid4().hex) 


对 于 DATABASE_URL 变量 ， 我 定义 了 一 个 MySQL URL。 我 将 在 下 一 节 中 向 你 介绍 如 何 配置 数 
据 库 。 


我 需要 将 FLASK_APP 环境 变量 设置 为 应 用 程序 的 入 口 点 以 启用 flask 命令 ， 但 在 解析 .emv 文 
件 之 前 需要 此 变量 ， 因 此 需要 手动 设置 。 为 避免 每 次 都 设置 它 ， 我 把 它 添加 到 ubuntu 帐户 的 
~/.profile 文 件 的 底部 ， 以 便 每 次 登录 时 自动 设置 它 : 


$ echo "export FLASK_APP=microblog.py" >> ~/.profile 


如 果 你 注销 并 重新 登录 ， 现 在 FLASK_APP 就 已 经 设置 好 了 。 你 可 以 通过 运行 flask --help 来 
确认 它 是 否 已 经 设置 好 了 。 如 果 帮 助 信息 显示 应 用 程序 已 添加 的 translate 命令 ， 那 么 你 就 
知道 应 用 程序 已 被 找到 。 


现在 flask 命令 是 有 效 的 ， 我 可 以 编译 语言 翻译 : 


(venv) $ flask translate compile 


1% a. MySQL 


我 在 开发 过 程 中 使 用 过 的 sqlite 数 据 库 非常 适合 简单 的 应 用 程序 ， 但 是 当 部 署 可 能 需要 一 次 处 
理 多 个 请 求 的 健壮 Web 服 务 器 时 ， 最 好 使 用 更 强大 的 数据 库 。 出 于 这 个 原因 ， 我 要 建立 一 个 
名 为 'microblog' 的 MySQL 数 据 库 。 


要 管理 数据 库 服 务 器 ， 我 将 使 用 mysql 命令 ， 该 命令 应 该 已 经 安装 在 你 的 服务 器 上 : 


$ mysql -u root -p 

Enter password: 

Welcome to the MySQL monitor. Commands end with ; or \g. 

Your MySQL connection id is 6 

Server version: 5.7.19-Oubuntu0.16.04.1 (Ubuntu) 

Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. 
Oracle is a registered trademark of Oracle Corporation and/or its 

affiliates. Other names may be trademarks of their respective 

owners. 

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. 


mysql> 


请 注意 ， 你 需要 键入 你 在 安装 MySQL 时 选择 的 MySQL root 密 码 才能 访问 MySQL 命 令 提 示 


这 些 是 创建 名 为 microblog 的 新 数据 库 的 命令 ， 以 及 具有 完全 访问 权限 的 同名 用 户 : 


mysql> create database microblog character set utf8 collate utf8_bin; 
mysql> create user 'microblog'@'localhost' identified by '<db-password>'; 
mysql> grant all privileges on microblog.* to 'microblog'@'localhost'; 
mysql> flush privileges; 

mysql> quit; 


你 将 需要 用 你 选择 的 密码 来 替换 <db-password> ° 这 将 是 microblog 数据 库 用 户 的 密码 ， 所 
以 不 要 使 用 你 已 为 root 用 户 选 择 的 密码 ° microblog 用 户 的 密码 需要 与 你 包含 在 .env 文 件 中 
的 DATABASE_URL 变量 中 的 密码 相 匹配 。 


如 果 你 的 数据 库 配 置 是 正确 的 ， 你 现在 应 该 能 够 运行 数据 库 迁 移 以 创建 所 有 的 表 : 


(venv) $ flask db upgrade 


续 下 一 步 之 前 ， 确 保 上 述 命令 成 功 完成 且 不 会 产生 任何 错误 。 


置 Gunicorn 和 Supervisor 


当 你 使 用 flask run 运行 服务 器 时 ， 正 在 使 用 的 是 Flask 附 带 的 Web 服 务 器 。 该 服务 器 在 开发 

过 程 中 非常 有 用 ， 但 它 不 适合 用 于 生产 服务 器 ， 因 为 它 不 考虑 性 能 和 稳健 性 。 取而代之 ， 我 
决定 使 用 gunicorn， 它 是 一 个 纯粹 的 Python Web 服 务 器 ， 但 与 Flask 不 同 ， 它 是 一 个 支持 高 并 
发 的 强大 生产 服务 器 ， 同 时 它 也 非常 容易 使 用 。 


要 在 gunicorn 下 启动 Microblog， 你 可 以 使 用 以 下 命令 


(venv) $ gunicorn -b localhost:8000 -w 4 microblog:app 


-b 选项 告诉 gunicorn 在 哪里 监听 请 求 ， 我 在 8000 端 口上 监听 了 内 部 网 络 接口 。 在 没有 外 部 
tt ea ot leis shige nn 快速 的 Web 
服务 器 ， 它 可 以 优化 来 自 客户 端的 所 有 静态 文件 的 请 求 。 快速 的 Web 服 务 器 将 直接 提供 
a 
将 nginx 设 置 为 面向 公众 的 服务 器 。 


-w 选项 配置 gunicorn 将 运行 多 少 Worker。 拥有 四 个 进程 可 以 让 应 用 程序 同时 处 理 多 达 四 个 客 
户 端 ， 这 对 于 Web 应 用 程序 通常 足以 处 理 大 量 客户 端 请 求 ， 因 为 并 非 所 有 客户 端 都 在 不 断 请 
RAŽ o 根据 服务 器 的 RAM 大 小 ， 你 可 能 需要 调整 worker 数 量 ， 以 免 内 存 不 足 。 


microblog:app 参数 告诉 gunicorn 如 何 加 载 应 用 程序 实例 。 冒号 前 的 名 称 是 包含 应 用 程序 的 模 
块 ， 冒 号 后 面 的 名 称 是 此 应 用 程序 的 名 称 。 


虽然 gunicorn 的 设置 非常 简单 ， 但 从 命令 行 运行 服务 器 在 生产 服务 器 实际 上 不 是 一 个 恰当 的 方 
Zo 我 想 要 做 的 是 让 服务 器 在 后 台 运 行 ， 并 持续 监视 ， 因 为 如 果 由 于 某 种 原因 导致 服务 器 崩 
演 并 退出 ， 我 想 确 保 新 的 服务 器 自动 启动 以 取代 它 。 而 且 我 还 想 确保 如 果 机 器 重新 启动 ， 服 


务 器 在 启动 时 自动 运行 ， 而 无 需 人 工 登 录 和 启动 。 我 将 使 用 上 面 安 装 的 supervisor 包 来 执行 此 


Supervisor 使 用 配置 文件 定义 它 要 监视 什么 程序 以 及 如 何在 必要 时 重新 启动 它们 。 配置 文件 
必须 存储 在 /etc/supervisor/conf.d 中 。 这 是 Microblog 的 配置 文件 ， 我 将 其 称 
A microblog.cont : 


/etc/supervisor/conf.d/microblog.conf : Supervisor 配 置 。 


[program:microblog] 
command=/home/ubuntu/microblog/venv/bin/gunicorn -b localhost:8000 -w 4 microblog:app 


directory=/home/ubuntu/microblog 
user=ubuntu 

autostart=true 

autorestart=true 
stopasgroup=true 
killasgroup=true 


command ， directory 和 user 设置 告 告诉 Supervisor 如 何 运行 应 用 程序 。 如果 计 算 机 启动 或 崩 
演 ， autostart 和 autorestart 设置 会 使 microblog 自 动 重新 启动 。 

stopasgroup 和 killasgroup 选项 确保 当 supervisor 需 要 停止 应 用 程序 来 重新 启动 它 时 ， 它 仍 
然 会 调度 成 顶级 gunicorn 进 程 的 子 进程 。 


编写 此 配置 文件 后 ， 必 须 重 载 supervisor 服 务 的 配置 才能 导入 它 


$ sudo supervisorctl reload 


像 这 样 ， 这 个 gunicorn web 服 务 器 就 已 经 启动 和 运行 ， 并 处 于 监控 之 中 | 


及 置 NginxX 


动 的 microblog 应 用 服务 器 现在 运行 在 本 地 端口 8000。 我 现在 需要 做 的 是 将 应 用 


程序 暴露 给 外 部 世界 ， 为 了 使 面向 公众 的 Web 服 务 器 能 够 被 访问 ， 我 在 防火 墙 上 打开 了 两 个 端 
口 (80 和 443) 来 处 理应 用 程序 的 Web 通 信 。 


我 希望 这 是 一 个 安全 的 部 署 ， 所 以 我 要 配置 端口 80 将 所 有 流量 转发 到 将 要 加 密 的 端口 443。 
我 将 首先 创建 一 个 SSL 人 证书。 创建 一 个 自 签 名 SSL 人 证 书 ， 这 对 于 测试 是 可 以 的 ， 但 对 于 丨 正 的 
部 署 不 太 好 ， 因 为 Web 浏 览 器 会 警告 用 户 ， 证 书 不 是 由 可 信 证 书 颁发 机 构 颁 发 的 。 创 建 
microblog 的 SSL 人 证书 的 命令 是 

$ mkdir certs 


$ openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \ 
-keyout certs/key.pem -out certs/cert.pem 


该 命令 将 要 求 你 提供 关于 应 用 程序 和 你 自己 的 一 些 信息 。 这 些 信息 将 包含 在 SSL 证 书 中 ， 如 
果 用 户 请 求 查 看 它 ，Web 浏 览 器 则 会 向 用 户 显示 它们 。 上 述 命 令 的 结果 将 是 名 为 key.pem 和 
cert.pem 的 两 个 文件 ， 我 将 其 放置 在 Microblog 根 目录 的 certs 子 目录 中 。 


要 有 一 个 由 nginx 服 务 的 网 站 ， 你 需要 为 它 编写 配置 文件 。 在 大 多 数 nginx 安 装 中 ， 这 个 文件 
需要 位 于 /etc/nginx/sites-enabled 目 录 中 。Nginx 在 这 个 位 置 安装 了 一 个 我 不 需要 的 测试 站 
点 ， 所 以 我 将 首先 删除 它 : 


$ sudo rm /etc/nginx/sites-enabled/default 


下 面 你 可 以 看 到 Microblog 的 nginx 配 置 文件 ， 它 在 /etc/nginx/sites-enabled/microblog 中 : 


/etc/nginx/sites-enabled/microblog : Nginx 配 置 。 


server { 
# listen on port 80 (http) 
listen 80; 
server_name _; 
location / { 
# redirect any requests to the same URL but on https 
return 301 https://$host$request_uri; 
} 
} 
server { 
# listen on port 443 (https) 
listen 443 ssl; 
server_name _; 


# location of the self-signed SSL certificate 
ssl_certificate /home/ubuntu/microblog/certs/cert.pem; 
ssl_certificate_key /home/ubuntu/microblog/certs/key.pem; 


# write access and error logs to /var/log 
access_log /var/log/microblog_access.1log; 
error_log /var/log/microblog_error.1log; 


location / { 
# forward application requests to the gunicorn server 
proxy_pass http://localhost : 8000; 
proxy_redirect off; 
proxy_set_header Host $host; 
proxy_set_header X-Real-IP $remote_addr; 
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 


} 


location /static { 
# handle static files directly, without forwarding to the application 
alias /home/ubuntu/microblog/static; 
expires 30d; 


Nginx 的 配置 不 多 理解 ， 但 我 添加 了 一 些 注 释 ， 至 少 你 可 以 知道 每 个 部 分 的 功能 。 如 果 你 想 获 
得 关于 特定 指令 的 信息 ， 请 参阅 nginx 官 方 文档 。 


添加 此 文件 后 ， 你 需要 告诉 nginx 重 新 加 载 配 置 以 激活 它 


$ sudo service nginx reload 


现在 应 用 程序 应 该 部 署 成 功 了 。 在 你 的 Web 浏 览 器 中 ， 可 以 键入 服务 器 的 IP 地 址 (如 果 使 用 
的 是 Vagrant VM， 则 为 192.168.33.10) ， 然 后 该 服务 器 将 连接 到 应 用 程序 。 由 于 你 使 用 的 是 
自 签名 证 书 ， 因 此 将 收 到 来 自 Web 浏 览 器 的 敬告， 你 必须 解除 该 警告 。 


使 用 上 述说 明 为 自己 的 项 目 完成 部 署 之 后 ， 我 强烈 建议 你 将 自 签名 证 书 蔡 换 为 真实 的 证 书 ， 
以 便 浏览 器 不 会 在 用 户 访问 你 的 网 站 时 发 出 警告 。 为 此 ， 你 首先 需要 购买 域名 并 将 其 配置 为 
指向 你 的 服务 器 的 IP 地 址 。 一 旦 你 有 一 个 域名 ， 你 可 以 申请 一 个 免费 的 Let's Encrypt SSL 证 
书 。 我 在 博客 上 写 了 一 篇 关于 如 何 通 过 HTTPS 运 行 你 的 Flask 应 用 程序 的 详细 文章 。 


部 因应 用 更 新 


我 想 讨论 的 基于 Linux 的 部 署 的 最 后 一 个 主题 是 如 何 处 理应 用 程序 升级 。 应 用 程序 源 代码 通 
过 git 安装 在 服务 器 中 ， 因 此 ， 无 论 何 时 想 要 将 应 用 程序 升级 到 最 新 版 本 ， 都 可 以 运 
行 git pull 来 下 载 自 上 次 部 署 以 来 的 新 提交 。 


当然 ， 下 载 新 版 本 的 代码 不 会 导致 升级 。 当 前 正在 运行 的 服务 器 进程 将 继续 运行 ， 旧 代码 已 
被 读 取 并 存储 在 内 存 中 。 要 触发 升级 ， 你 必须 停止 当前 的 服务 器 并 启动 一 个 新 的 服务 器 ， 以 
强制 重新 读 取 所 有 代码 。 


进行 升级 通常 比重 新 启动 服务 器 更 为 复杂 。 你 可 能 需要 应 用 数据 库 迁 移 或 编译 新 的 语言 番 
译 ， 因 此 实际 上 上， 执行 升级 的 过 程 涉及 一 系列 命令 


(venv) $ git pull # download the new version 
(venv) $ sudo supervisorctl stop microblog # stop the current server 
(venv) $ flask db upgrade # upgrade the database 
(venv) $ flask translate compile # upgrade the translations 
(venv) $ sudo supervisorctl start microblog # start a new server 


A IRIE 


树 莽 派 是 一 款 革 命 性 低 成 本 的 小 型 Linux 计 算 机 ， 功 耗 非常 低 ， 因 此 它 是 托管 家 庭 在 线 服务 器 
te a a a E 记 本 电脑 。 有 几 个 Linux 发 行 版 可 
以 在 树 荐 派 上 运行 。 我 的 选择 是 Raspbian， 这 是 树 莓 派 基金 会 的 官方 发 行 版 。 


为 了 准备 树 莓 派 的 环境 ， 我 要 安装 一 个 新 的 Raspbian 版 本 。 我 将 使 用 2017 年 9 月 版 的 
Raspbian Stretch Lite， 但 在 阅读 本 文 时 ， 可 能 会 有 更 新 的 版 本 ， 请 查看 官方 下 载 页 面 获 得 最 
新 版 本 。 


Raspbian 镜 像 需 要 安装 在 SD 卡 上 ， 然 后 插入 树 荐 派 ， 以 便 它 启动 时 可 以 识别 到 。 AM AIRS 
点 上 可 以 查看 到 从 Windows，Mac OS X 和 Linux 将 Raspbian 镜 像 复制 到 SD 卡 的 方法 。 


GRA KE AMIR > ESR fe LARAMIE VUEIR T AATE o B 
少 应 该 启用 SSH， 以 便 你 可 以 从 计算 机 登录 并 方便 地 执行 部 署 任务 


和 Ubuntu 一 样 ，Raspbian 也 是 Debian 的 衍生 产品 ， 所 以 上 面 针 对 的 Ubuntu Linux 的 说 明 ， 大 
SR ART VATE BREA Ko 但 是 ， 如 果 你 计划 在 家 庭 网 络 上 运行 小 型 应 用 程序 而 无 需 外 部 
访问 时 ， 则 可 以 跳 过 茶 些 步骤 。 例如， 你 可 能 不 需要 防火 墙 或 无 密码 登录 。 你 可 能 想 在 这 样 

台 小 型 的 计算 机 上 使 用 SQLite 而 不 是 MySQL。 你 可 以 选择 不 使 用 nginx， 并 且 让 gunicorn 服 
务 器 直接 监听 来 自 客户 端的 请 求 。 你 可 能 只 想 要 一 个 gunicorn worker 进 程 。 
对 于 确保 应 用 程序 始终 处 于 运行 状态 非常 有 用 ， 因 此 我 建议 你 仍然 在 树 基 派 上 使 用 它 


本 文 翻 译 自 The Flask Mega-Tutorial Part XVIII: Deployment on Heroku 
这 是 Flask Mega-Tutorial 系 列 的 第 十 入 部 分 ， 我 将 在 其 中 部 署 Microblog 到 Heroku 云 平台 。 


在 前 面 的 文章 中 ， ds cee le ， 并 且 我 演示 了 两 个 部 署 到 
Linux 的 服务 器 的 实际 示例 。 如 果 你 不 曾 at Linux A A 么 你 可 能 认为 需要 投入 大 量 工 
作 到 这 项 任务 中 ， ee o 


在 本 章 中 ， 我 将 向 你 展示 一 种 完全 不 同 的 部 署 方法 ， 该 方法 依赖 第 三 方 云 托管 提供 程序 来 执 
行 大 部 分 管理 任务 ， 从 而 使 你 能 够 腾 出 更 多 时 间 处 理应 用 程序 。 


许多 云 托 管 提 供 商 提供 了 一 个 应 用 程序 可 以 运行 的 托管 平台 。 你 只 需 提 供 部 署 到 这 些 平台 上 
的 实际 应 用 程序 ， 因 为 硬件 ， 操 作 系 统 ， 脚 本 语言 解释 器 ， 数 据 库 等 都 由 该 服务 管理 。 这 种 
服务 称 为 平台 即 服务 (PaaS) 。 


是 不 是 感到 难以 置信 ? 


我 将 把 Microblog 部 署 到 Heroku， 这 是 一 种 流行 的 云 托管 服务 ， 对 Python 应 用 程序 也 非常 友 


好 。 我 选择 Heroku 不 仅仅 是 因为 它 非 常 受 欢迎 ， 还 因为 它 有 一 个 免费 的 服务 级 别 ， 可 以 让 你 
跟随 我 并 在 不 花 钱 的 情况 下 完成 部 署 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


托管 于 Heroku 


Heroku 是 首 批 PaaS 平 台 之 一 。 它 以 Ruby 的 应 用 程序 的 托管 服务 开始 ， 随 后 逐渐 发 展 到 支持 
诸多 其 他 语言 ， 如 Java，Node.js 和 Python。 


在 Heroku 中 部 署 Web 应 用 程序 主要 是 通过 git 版 本 控制 工具 完成 的 ， 因 此 你 必须 将 应 用 程序 
放 在 git 代 码 库 中 。 Heroku 在 应 用 程序 的 根 目录 中 查找 名 为 Procfile 的 文件 ， 以 获取 有 关 如 何 启 
动 应 用 程序 的 描述 。 对 于 Python 项 目 ，Heroku 还 期 望 requirements.txt 文 件 列 出 需要 安装 的 所 
有 模块 依赖 项 。 在 通过 git 将 应 用 程序 上 传 到 Heroku 的 服务 器 之 后 ， 你 的 工作 基本 就 完成 了 ， 
只 需 等 待 几 秒 钟 ， 应 用 程序 就 会 上 线 。 整个 操作 流程 就 是 这 么 简单 。 


Heroku 提 供 不 同 的 服务 级 别 ， 允 许 你 自主 选择 为 应 用 程序 提供 多 少 计 算 能 力 和 运行 时 间 ， 随 
着 用 户 群 的 增长 ， 你 需要 购买 更 多 的 “dynos” 计 算 单元 。 


准备 好 了 吗 ? 让 我 们 开始 吧 | 
创建 Heroku 账 户 
在 部 署 应 用 到 Heroku 之 前 ， 你 需要 拥有 一 个 帐户 。 所 以 请 访问 heroku.com 并 创建 一 个 免费 账 


户 。 一 旦 注册 成 功 并 登录 到 Heroku， 你 将 可 以 访问 一 个 dashboard， 其 中 列 出 了 你 的 所 有 应 
用 程序 。 


安装 Heroku 命 令 行 客户 端 


Heroku 提 供 了 一 个 名 为 Heroku CLI 的 命令 行 工具 来 与 服务 交互 ， 可 安装 于 Windows > Mac 
OS X 和 Linux。 该 文档 包括 了 支持 的 所 有 平台 的 安装 说 明 。 如 果 你 计划 部 署 应 用 程序 以 测试 
该 服务 ， 请 将 其 安装 在 你 的 系统 上 。 Heroku provides a command-line tool for interacting 
with their service called Heroku CLI, available for Windows, Mac OS X and Linux. The 
documentation includes installation instructions for all the supported platforms. Go ahead 
and install it on your system if you plan on deploying the application to test the service. 


安装 CLI 后 应 该 做 的 第 一 件 事 是 登录 到 你 的 Heroku 帐 户 : 


$ heroku login 


Heroku CLI 会 要 求 你 输入 电子 邮件 地 址 和 帐户 密码 。 你 的 身份 验证 状态 将 在 随后 的 命令 中 被 
记 住 。 


x i Git 


git 工具 是 Heroku 应 用 程序 部 署 的 核心 ， soca 还 没有 安装 它 的 话 ， 则 必须 将 它 安装 到 
你 的 系统 上 。 如 果 你 没有 可 用 于 你 的 操作 系统 的 安装 包 ， 可 以 访问 git site 下 载 安 装 程序 。 


使 用 git 的 原因 很 多 并 且 都 理由 充分 。 如 果 你 打算 部 署 应 用 到 Heroku， 那 么 这 些 原因 就 要 又 
增加 一 个 ， 因 为 要 部 署 应 用 到 Heroku， 你 的 应 用 程序 必须 在 git 代码 库 中 。 如 果 你 要 为 
Microblog 执 行 测试 部 署 ， 可 以 从 GitHub 克 隆 应 用 程序 : 


$ git clone https://github.com/miguelgrinberg/microblog 
$ cd microblog 
$ git checkout v0.18 


git checkout 命令 将 代码 库 切 换 到 指定 的 历史 提交 点 ， 也 就 是 本 章 所 处 的 位 置 。 


如 果 更 喜欢 使 用 你 自己 的 代码 ， 你 可 以 通过 在 顶层 目录 中 运行 git init . 来 将 你 自己 的 项 目 
转换 成 git 代码 库 (注意 init 后 面 的 句号 ， 它 告诉 git 你 想 要 在 当前 目录 中 初始 化 代码 
库 ) 。 


创建 Heroku 应 用 


要 用 Heroku 注 册 一 个 新 应 用 ， 需 要 在 应 用 程序 根 目 录 下 使 用 apps:create 子 命令 ， 并 将 应 用 
程序 名 称 作 为 唯一 参数 传递 : 


$ heroku apps:create flask-microblog 
Creating flask-microblog... done 
http://flask-microblog.herokuapp.com/ | https://git.heroku.com/flask-microblog.git 


Heroku 要 求 应 用 程序 的 名 称 具有 唯一 性 。 我 上 面 已 使 用 了 flask-microblog 这 个 名 称 ， 所 以 
你 需要 为 你 的 部 署 选择 一 个 不 同 的 名 称 。 


该 命令 的 输出 将 包含 Heroku 分 配给 应 用 程序 的 URL 以 及 git 代 码 库 。 你 的 本 地 git 代 码 库 将 配置 
一 个 额外 的 remole， 称 为 heroku ° 你 可 以 用 git remote 命令 验证 它 是 否 存在 : 


$ git remote -V 
heroku https://git.heroku.com/flask-microblog.git (fetch) 
heroku https://git.heroku.com/flask-microblog.git (push) 


根据 你 创建 git 代 码 库 的 方式 ， 上 述 命令 的 输出 还 可 能 包含 另 一 个 名 为 origin 的 远程 仓库 地 
址 。 


临时 文件 系统 


Heroku 平 台 与 其 他 部 署 平台 不 同 之 处 在 于 它 在 虚拟 化 平台 上 和 运行 的 文件 系统 是 临时 的 。 那 是 
什么 意思 9 这 意味 着 Heroku 可 以 随时 将 运行 你 的 应 用 的 虚拟 服务 器 重 置 为 干净 状态 。 你 不 访 
天 昌 地 认为 你 保存 到 文件 系统 的 任何 数据 都 会 被 持久 存储 ， 事 实 上 ，Heroku 经 常 回收 服务 


Ba 


an 
o 


在 这 种 条 件 下 工作 会 为 我 的 应 用 程序 带 来 一 些 问题 ， 因 为 它 使 用 了 如 下 的 几 个 文件 : 


e 默认 的 SQLite 数 据 库 引擎 将 数据 写 入 磁盘 文件 中 
。 应 用 程序 的 日 志 也 写 入 磁盘 文件 中 
© 编译 的 语言 翻译 存储 库 同 样 是 本 地 文件 


以 下 部 分 将 针对 这 三 个 方面 提出 解决 方案 。 


使 用 Heroku Postgres 数 据 库 


为 了 解决 第 一 个 问题 ， 我 将 切换 到 不 同 的 数据 库 引 擎 。 在 第 十 七 章 中 ， 你 看 到 我 使 用 MySQL 
数据 库 为 Ubuntu 部 署 添 加 健壮 性 。 Heroku 基 于 Postgres 数 据 库 提 供 了 自己 的 数据 库 产品 ， 
此 我 将 转 而 使 用 它 来 避免 使 用 基于 文件 的 SQLite © 


Heroku 应 用 的 数据 库 使 用 相同 的 Heroku CLI 进 行 设 置 。 在 本 章 中 ， 我 将 创建 一 个 免费 级 别 的 
数据 库 : 


$ heroku addons:add heroku-postgresql:hobby-dev 
Creating heroku-postgresql:hobby-dev on flask-microblog... free 
Database has been created and is available 
! This database is empty. If upgrading, you can transfer 
! data from another database with pg:copy 
Created postgresql-parallel-56076 as DATABASE_URL 
Use heroku addons:docs heroku-postgresql to view documentation 


新 创建 的 数据 库 的 URL 存 储 在 DATABASE_URL 环境 变量 中 ， 该 变量 在 应 用 程序 运行 时 将 可 用 。 
这 就 非常 方便 了 ， 因 为 应 用 程序 已 经 设 定 为 在 该 变量 中 查找 数据 库 URL 。 


输出 日 志 到 标准 输出 


Heroku 和 希望 应 用 程序 直接 输出 日 志 到 stdout 。 当 你 使 用 heroku logs 命令 时 ， 应 用 程序 打印 
到 标准 输出 的 任何 内 容 都 将 被 保存 并 返回 。 所 以 我 要 添加 一 个 配置 变量 ， 指 示 我 是 要 输出 日 
志 到 stdout ， 还 是 像 我 之 前 那样 输出 到 文件 。 这 是 配置 的 变化 : 


config.py : 输出 日 志 到 标准 输出 的 选项 。 


class Config(object): 
# i... 
LOG_TO_STDOUT = os.environ.get('LOG_TO_STDOUT' ) 


然后 在 应 用 工厂 函数 中 ， 我 会 检查 此 配置 以 了 解 应 该 如 何 配置 应 用 程序 的 日 志 记 录 器 : 


app/__init_.py : 输出 日 志 到 标准 输出 或 文件 。 


def create_app(config_class=Config): 


if not app.debug and not app.testing: 
# a. 


if app.config['LOG_TO_STDOUT']: 
stream_handler = logging.StreamHandler () 
stream_handler.setLevel( logging. INFO) 
app. logger .addHandler(stream_handler ) 
else: 
if not os.path.exists('logs'): 
os.mkdir('logs') 
file_handler = RotatingFileHandler('logs/microblog.log', 
maxBytes=10240, backupCount=10) 
file_handler.setFormatter(logging.Formatter( 
"%(asctime)s %(levelname)s: %(message)s ' 
"Tin %(pathname)s:%(lineno)d]')) 
file_handler.setLevel( logging. INFO) 
app. logger .addHandler(file_handler ) 


app. logger .setLevel( logging. INFO) 
app.logger.info('Microblog startup') 


return app 


所 以 现在 我 需要 在 Heroku 中 运行 应 A LOG_TO_STDOUT 环境 变量 ， 但 在 其 他 配置 中 
则 不 需要 。 Heroku CLI 使 得 做 到 这 变 得 简单 ， 因 为 它 提 供 了 一 个 选项 来 设置 运行 时 使 用 
的 环境 变量 : 


$ heroku config:set LOG_TO_STDOUT=1 
Setting LOG_TO_STDOUT and restarting flask-microblog... done, v4 
LOG_TO_STDOUT: 1 


编译 翻译 


Microblog 依 赖 本 地 文件 的 第 三 个 方面 是 编译 后 的 语言 翻译 文件 。 确 保 这 些 文件 永远 不 会 从 临 
时 文件 系统 中 消失 的 粗暴 做 法 是 将 编译 后 的 语言 文件 添加 到 git 代 码 库 ， 以 便 在 部 署 到 Heroku 
后 它们 成 为 应 用 程序 初始 状态 的 一 部 分 


在 我 看 来 7 更 优雅 的 选择 是 在 Heroku 的 尼 命令 中 包 包含 flask translate compile 命令 ， 以 便 
在 服务 器 重新 启动 时 再 次 编译 这 些 文件 。 ere rer 首 局 动 过 程 需要 多 
个 命令 ， 至 少 我 还 需要 运行 数据 库 迁 移 。 所 以 现在 ， 我 将 把 这 个 问题 放 在 一 边 ， 稍 后 当 我 写 
Procfile 的 时 候 会 重新 讨论 它 。 


托管 Elasticsearch 


Elasticsearch 是 可 以 添加 到 Heroku 项 目 中 的 众多 服务 之 一 ， 但 与 Postgres 不 同 的 是 ， 这 不 是 
由 Heroku 提 供 的 服务 ， 而 是 由 与 Heroku 合 作 提 供 附加 组 件 的 第 三 方 提供 的 。 在 我 写 这 篇 文章 
的 时 候 ， 有 三 个 不 同 的 集成 Elasticsearch 服 务 提供 商 。 


在 配置 Elasticsearch 之 前 ， 请 注意 ，Heroku 要 求 你 的 帐户 在 安装 任何 第 三 方 附 加 组 件 之 前 添 
加 信用 卡 信息 ， 即 使 你 仍 处 于 在 免费 级 别 中 。 如 果 你 不 想 将 信用 卡 信 息 提 供给 Heroku， 请 跳 
过 此 部 分 。 你 仍然 可 以 部 署 应 用 程序 ， 但 搜索 功能 不 起 作用 。 


在 可 作为 附加 组 件 提 供 的 Elasticsearch 选 项 中 ， 我 决定 尝试 SearchBox， 它 pas 的 初 
试 计 划 。 要 将 SearchBox 添 加 到 你 的 帐户 ， 你 必须 在 登录 到 Heroku 后 运行 以 下 命 


$ heroku addons:create searchbox:starter 


该 命令 将 部 闭 一 个 Flasticsearch 服 务 ， 并 将 该 服务 的 连接 URL 保 存在 与 你 的 应 用 程序 关联 
的 SEARCHBOX_URL 环境 变量 中 。 请 记 住 ， 除 非 将 你 的 信用 卡 信 息 添加 到 你 的 Heroku 帐 户 中 ， 
否则 此 命 令 将 失败 。 


回忆 一 下 第 十 六 章 ， 我 的 应 用 程序 在 Elasticsearch 连 接 URL 中 查找 的 是 ELASTICSEARCH_URL 变 
量 ， 所 以 我 需要 添加 这 个 变量 并 将 其 设置 为 由 SearchBox 分 配 的 连接 URL : 


$ heroku config:get SEARCHBOX_URL 
<your-elasticsearch-url> 
$ heroku config:set ELASTICSEARCH_URL=<your -elasticsearch-url> 


在 这 里 ， 我 首先 要 求 Heroku 打 印 SEARCHBOX_URL 的 值 ， 然 后 将 其 添加 到 一 个 名 


为 ELASTICSEARCH_URL 的 新 环境 变量 中 。 


更 新 依赖 
Heroku 期 望 依赖 关系 在 requirements.txt 文 件 中 ， 就 像 我 在 第 十 五 草 中 定义 的 那样 。 但 是 为 了 
在 Heroku 上 运行 应 用 程序 ， 我 需要 为 这 个 文件 添加 两 个 新 的 依赖 关系 。 


Heroku 不 提供 自己 的 Web 服 务 器 。 相反， 它 希 望 应 用 程序 根据 环境 变量 sport 中 给 出 的 端口 
号 启动 自己 的 Web 服 务 器 。 由 于 Flask 开 发 Web 服 务 器 不 足以 用 于 生产 ， 因 此 我 将 再 次 使 
用 gunicorn， 这 是 Heroku 为 Python 应 用 程序 推荐 的 服务 器 。 


该 应 用 程序 还 将 连接 到 Postgres 数 据 库 ， 为 此 SQLAIlchemy 依 赖 psycopg2 软件 包 的 安装 。 


gunicorn 和 psycopg2 都 需要 添加 到 requirements.txt 文 件 中 。 


Procfile 


Heroku 需 要 知道 如 何 执 行 应 用 程序 ， 并 且 它 会 在 应 用 程序 的 根 目 录 中 使 用 名 为 Procfile 的 文 
件 。 这 个 文件 的 格式 很 简单 ， 每 行 包含 一 个 进程 名 称 ， 一 个 冒号 ， 然 后 是 启动 进程 的 命令 。 
在 Heroku 上 运行 的 最 常见 的 应 用 程序 类 型 是 一 个 Web 应 用 程序 ， 对 于 这 种 类 型 的 应 用 程序 ， 
进程 名 称 应 该 是 web 。 下面 你 可 以 看 到 Microblog 的 Procfile : 


Procfile : Heroku Procfile ° 


web: flask db upgrade; flask translate compile; gunicorn microblog:app 


在 这 里 ， 我 定义 的 启动 命令 中 将 按 顺序 执行 三 个 命令 作 以 启动 Web 应 用 程序 。 首先 ， 我 运 和 
数据 库 迁 移 升 级 ， 然 后 编译 语言 翻译 ， 最 后 启动 服务 


因为 前 两 个 子 命令 是 基于 flask 命令 的 ， 所 以 我 需要 添加 FLASK_APP 环境 变量 : 


$ heroku config:set FLASK_APP=microblog.py 
Setting FLASK_APP and restarting flask-microblog... done, v4 
FLASK_APP: microblog.py 


gunicorn 命令 比 我 用 于 Ubuntu 部 署 的 还 要 简单 ， 因 为 这 个 服务 与 Heroku 环 境 有 很 好 的 集成 。 
例如 ， $poRT 环境 变量 默认 会 被 设置 ， 取 代 使 用 -w 选项 来 设置 worker 的 数量 ，heroku 推 荐 
添加 一 个 名 为 WEB_CONCURRENCY 的 环境 变量 ， 在 -w 参数 没有 提供 的 时 候 ， 就 会 使 用 这 个 环境 


变量 ， 因 此 你 可 以 灵活 地 控制 Worker 的 数量 而 无 需 修 改 Procfile 。 


部 署 应 用 


所 有 准备 步骤 都 已 完成 ， 所 以 现在 是 时 候 执行 部 署 了 。 要 将 应 用 程序 上 传 到 Heroku 的 服务 器 
进行 部 署 ， 需 要 使 用 git push TA ° 这 与 你 将 本 地 git 代 码 库 中 的 更 改 推送 到 GitHub 或 其 他 远 
程 git 服 务 器 的 方式 类 似 。 

现在 我 已 经 达到 了 最 有 趣 的 部 分 ， 就 是 将 应 用 程序 推送 到 我 们 的 Heroku 托 管 帐户 。 这 其 实 很 
简单 ， 我 只 需要 使 用 git 将 应 用 程序 推送 到 Heroku git 代 码 库 的 主 分 支 就 行 了 。 关于 如 何 做 
到 这 一 点 有 几 种 方法 ， 取 决 于 你 是 如 何 创建 你 的 git 代 码 库 的 。 如 果 你 使 用 我 的 ve.18 代码 ， 
那么 你 需要 基于 此 标记 创建 一 个 分 支 ， 并 将 其 作为 远程 主 分 支 推送 ， 如 下 所 示 : 


$ git checkout -b deploy 
$ git push heroku deploy:master 


相反 ， 如 果 你 正在 使 用 自己 的 代码 库 ， 那 么 你 的 代码 已 经 在 master 分 支 中 ， 所 以 你 首先 需要 
确保 你 的 更 改 已 经 提交 : 


$ git commit -a -m "heroku deployment changes" 


$ git push heroku master 


无 论 你 如 何 推送 分 支 ， 都 应 该 看 到 Heroku 的 以 下 输出 : 


$ git push heroku deploy:master 

Counting objects: 247, done. 

Delta compression using up to 8 threads. 

Compressing objects: 100% (238/238), done. 

Writing objects: 100% (247/247), 53.26 KiB | 3.80 MiB/s, done. 
Total 247 (delta 136), reused 3 (delta 0) 


remote: Compressing source files... done. 
remote: Building source: 
remote: 
remote: ----- > Python app detected 
remote: ----- > Installing python-3.6.2 
remote: ----- > Installing pip 
remote: ----- > Installing requirements with pip 
remote: 
remote: ----- > Discovering process types 
remote: Procfile declares types -> web 
remote: 
remote: ----- > Compressing... 
remote: Done: 57M 
remote: ----- > Launching... 
remote: Released v5 
remote: https://flask-microblog.herokuapp.com/ deployed to Heroku 
remote: 
remote: Verifying deploy... done. 
To https://git.heroku.com/flask-microblog.git 
* [new branch] deploy -> master 


我 们 在 git push 命令 中 使 用 的 标签 heroku 是 在 创建 应 用 程序 时 由 Heroku CLI 自 动 添加 的 远 
程 代 码 库 。 deploy:master 参数 意味 着 我 将 代码 从 本 地 代码 库 的 deploy 分 支 推送 到 Heroku 代 
码 库 上 的 master 分 支 。 当 你 使 用 自己 的 项 目 时 ， 你 da git push heroku master 命令 推 
动 你 的 本 地 master 分 支 。 由 于 这 个 项 目的 代码 库 分 支 结 构 ， 我 推送 了 一 个 非 master 的 分 
支 ， 但 Heroku 侧 要 求 的 目标 分 支 是 'master， 因 为 这 是 Heroku 唯 一 接受 部 署 的 分 支 


就 这 样 ， 应 用 程序 现在 应 该 已 经 部 署 在 创建 应 用 程序 的 命令 的 输出 中 给 出 的 URL 上 了 。 在 我 
的 案例 中 ，URL 是 https:/flask-microblog.herokuapp.com， 所 以 这 就 是 我 需要 键入 和 访问 该 应 
用 程序 的 URL 。 


如 果 你 想 查 看 正在 运行 的 应 用 程序 的 日 志 ， 请 使 用 heroku logs 命令 。 如 果 由 于 任何 原因 导 
致 应 用 程序 无 法 启动 ， 该 命令 可 能 很 有 用 。 如 果 有 任何 错误 ， 将 在 日 志 中 显示 。 


部 因应 用 更 新 


要 部 署 新 版 本 的 应 用 程序 ， 只 需要 使 用 git push 命令 将 新 的 代码 库 推送 到 Heroku 即 可 。 
将 重复 部 署 过 程 ， 关 停 旧 部 署 ， 然 后 用 新 代码 替换 它 。 Procfile 中 的 命 peace rans 
分 再 次 运行 ， 因 此 在 此 过 程 中 将 更 新 任何 新 的 数据 库 迁 移 或 翻译 内 容 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part XIX: Deployment on Docker Containers 
这 是 Flask Mega-Tutorial 系 列 的 第 十 九 部 分 ， 我 将 在 其 中 部 署 Microblog 到 Docker 容 器 平台 。 


在 第 十 七 章 中 ， 你 了 解 了 传统 部 署 ， 使 用 这 种 部 署 方式 ， 你 必须 关注 服务 器 配置 的 每 个 细 

节 。 然后 在 第 十 八 章 我 带 你 到 另 一 个 极端 一 一 Heroku ， 这 是 一 项 完全 掌控 配置 和 部 署 任 务 的 
服务 ， 使 你 能 够 全 神 贯 注 于 应 用 程序 。 在 本 章 中 ， 你 将 学 习 基 于 容器 (尤其 是 在 Docker 容 器 
平台 ) 的 第 三 种 应 用 程序 部 署 策略 。 这 种 部 署 的 工作 量 ， 介 于 另外 两 个 选项 之 间 。 


容器 建立 在 轻 量 级 虚拟 化 技术 的 基础 上 ， 允 许 应 用 程序 及 其 依赖 和 配置 完全 隔离 宿主 机 地 运 
行 ， 而 不 需要 使 用 虚拟 机 等 完整 的 虚拟 化 解决 方案 。 使 用 虚拟 机 需要 更 多 的 资源 ， 并 且 有 时 
可 能 与 宿主 机 相 比 ， 性 能 显著 下 降 。 配置 为 容器 宿主 机 的 系统 可 以 运行 大 量 容器 ， 所 有 这 些 
容器 共享 主机 的 内 核 并 直接 访问 主机 的 硬件 。 这 与 虚拟 机 不 同 ， 虚拟 机 必须 模拟 完整 的 系 

统 ， 包 括 CPU， 磁 盘 ， 其 他 硬件 ， 内 核 等 。 


S 
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尽管 必须 共享 内 核 ， 但 容器 中 的 隔离 级 别 非 常 高 。 容 器 具有 自己 的 文件 系统 ， 并 且 可 以 基于 
容器 宿主 机 使 用 不 同 的 操作 系统 。 例 如 ， 你 可 以 在 Fedora 窒 主机 上 运行 基于 Ubuntu Linux 的 
容器 ， 反 之 亦 然 。 尽 管 容器 是 Linux 操 作 系 统 上 诞生 的 技术 ， 但 由 于 虚拟 化 的 原因 ， 也 可 以 在 
Windows 和 Mac OS X 窒 主机 上 运行 Linux 容 器 。 这 允许 你 在 开发 系统 上 测试 部 署 操作 ， 并 且 
如 果 你 愿意 的 话 ， 还 可 以 将 容器 合并 到 开发 工作 流程 中 去 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


2 & Dockertt R hk 


尽管 Docker 不 是 唯一 的 容器 平台 ， 但 它 是 迄今 为 止 最 受 欢迎 的 ， 所 以 我 选择 了 它 。 有 两 个 版 
本 的 Docker， 免 费 的 社区 版 (CE) 和 付费 的 企业 版 (EE) 。 对 于 本 教程 来 说 ，Docker CE 
RÉT ° 


24% M Docker CE， 首 先 必 须 将 其 安装 在 系统 上 。 在 Docker 网 站 上 有 适用 于 Windows，Mac 
OS X 和 多 个 Linux 发 行 版 的 安装 程序 。 如果 你 正在 使 用 Microsoft Windows 系 统 ， 请 务必 注意 
Docker CE 依赖 Hyper-V。 如 有 必要 ， 安 装 程序 将 为 你 启用 此 功能 ， 但 请 记 住 ， 启 用 Hyper-V 
会 限制 诸如 VirtualBox 等 其 他 虚拟 化 技术 产品 的 运行 。 


一 旦 Docker CE 安装 在 你 的 系统 上 ， 你 可 以 通过 在 终端 窗口 或 命令 提示 符 处 输入 以 下 命令 来 验 


$ docker version 


Client: 

Version: 17.09.0-ce 

API version: 1.32 

Go version: go1.8.3 

Git commit: afdb6d4 

Built: Tue Sep 26 22:40:09 2017 
OS/Arch: darwin/amd64 

Server: 

Version: 17.09.0-ce 

API version: 1.32 (minimum version 1.12) 
Go version: go1.8.3 

Git commit: afdb6d4 

Built: Tue Sep 26 22:45:38 2017 
OS/Arch: linux/amd64 


Experimental: true 


pues 容器 的 第 一 步 是 为 Pona 容器 镜像 是 用 于 创建 容器 的 模板 。 它 包 
含 容器 文件 系统 的 完整 表示 ， 以 及 与 网 络 ， 选项 等 相关 的 各 种 设置 。 


为 应 用 程序 创建 容器 镜像 的 最 基本 方法 是 启动 一 个 要 使 用 的 基本 操作 系统 (Ubuntu > Fedora 

F) 容器 ， 连 接 到 运行 在 其 中 的 bash shell 进 程 ， 然 后 手动 安装 应 用 程序 ， 可 以 参照 我 在 第 十 

七 章 b 介绍 的 流程 进行 传统 部 署 。 安装 完 所 有 内 容 后 ， 你 可 以 保存 容器 的 快照 ， 并 生成 容器 

。 docker 命令 支持 这 种 类 型 的 工作 流 ， 但 我 不 打算 讨论 这 种 方法 ， 因 为 它 非常 不 便 ， 每 
次 需要 生成 新 镜像 时 都 必须 手动 安装 应 用 程序 。 


更 好 的 方法 是 通过 脚本 生成 容器 镜像 。 创建 脚本 化 容器 镜像 的 命令 是 docker build 。 该 命令 
从 一 个 名 为 Dockerfile 的 文件 读 取 并 执行 构建 指令 — | 建 这 些 指令 ) © Dockerfile 基 本 
上 可 以 认为 是 一 个 安装 程序 脚本 ， 它 执行 安装 步骤 来 部 署 应 用 程序 ， 以 及 一 些 容 器 特定 的 设 
置 。 


这 是 Microblog 的 一 份 基础 的 Dockerfile : 


Dockerfile: Microblog 的 Dockerfile。 


FROM python:3.6-alpine 
RUN adduser -D microblog 
WORKDIR /home/microblog 


COPY requirements.txt requirements.txt 

RUN python -m venv venv 

RUN venv/bin/pip install -r requirements.txt 
RUN venv/bin/pip install gunicorn 


COPY app app 

COPY migrations migrations 

COPY microblog.py config.py boot.sh ./ 
RUN chmod +x boot.sh 


ENV FLASK_APP microblog.py 


RUN chown -R microblog:microblog ./ 
USER microblog 


EXPOSE 5000 
ENTRYPOINT ["./boot.sh"] 


这 样 一 来 ， 你 从 一 个 现 有 的 镜像 开始 ， 添 加 或 改变 一 些 东 西 ， 并 最 终 得 到 一 个 派生 的 镜像 。 
镜像 由 名 称 和 标签 来 标记 ， 它 们 之 间 用 冒号 分 隔 。 该 标签 用 作 版 本 控制 机 制 ， 允 许 容 器 镜像 
提供 多 个 版 本 。 我 选择 的 镜像 的 名 称 是 python ， 它 是 Python 的 官方 Docker 镜 像 。 该 镜像 的 
标签 允许 你 指定 解释 器 版 本 和 基础 操作 系统 。 3.6-alpine 标签 选择 安装 在 Alpine Linux 上 的 
Python 3.6 解 释 器 。 由 于 其 体积 小 ，Alpine Linux 发 行 版 比 起 更 常见 的 发 行 版 〈 例 如 Ubuntu ) 
会 更 多 地 被 使 用 。 你 可 以 在 Python 镜像 库 中 查看 Python 镜像 可 用 的 标签 。 


Dockerfile 中 的 每 一 行 都 是 一 条 命令 。 FROM 命令 指定 将 在 其 上 构建 新 镜像 的 基础 容器 镜像 。 


RUN 命令 在 容器 的 上 下 文中 执行 任意 命令 。 这 与 你 在 shell 提 示 符 下 输入 命令 相似 。 

adduser -D microblog 命令 创建 一 个 名 为 microblog 的 新 用 户 。 大 多 数 容器 镜像 都 使 

用 root 作为 默认 用 户 ， 但 以 root 身 份 运行 应 用 程序 并 不 是 一 个 好 习惯 ， 所 以 我 创建 了 自己 的 
用 户 。 


WORKDIR 命令 设置 将 要 安装 应 用 程序 的 默认 目录 。 当 我 在 上 面 创建 microblog 用 户 时 ， 会 自 
动 创建 了 一 个 主 目 录 ， 所 以 现在 我 将 该 目录 设置 为 默认 目录 。 在 Dockerfile 中 的 任何 剩余 命令 
执行 以 及 运行 容器 时 ， 其 当前 目录 为 这 个 默认 目录 。 


copy 命令 将 文件 从 你 的 机 器 复制 到 容器 文件 系统 。 该 命令 需要 两 个 或 更 多 参数 ， 源 文件 / 目 
录 和 目标 文件 /目录 。 源 文件 必须 与 Dockerfile 所 在 的 目录 相关 。 目的 地 可 以 是 绝对 路 径 ， 也 
可 以 是 相对 于 在 之 前 的 woRKDIR 命令 中 设置 的 目录 的 路 径 。 在 这 第 一 个 copy 命令 中 ， 我 

将 requirements.txt 文 件 复制 到 容器 文件 系统 的 microblog 用 户 的 主 目录 中 。 


容器 中 有 了 requirements.txt 文 件 ， 我 就 可 以 使 用 RUN 命令 创建 一 个 虚拟 环境 。 首 先 我 创建 
它 ， 然 后 在 其 中 安装 所 有 依赖 。 由 于 依赖 文件 仅 包含 通用 依赖 项 ， 因 此 我 明确 安装 
gunicorn， 以 将 其 用 作 Web 服 务 器 。 当 然 ， 我 也 可 以 在 我 的 requirements.txt 文 件 中 添加 
gunicorn ° 


接 下 来 的 三 个 coy 命令 从 顶级 目录 中 复制 gpp 包 ， 含 有 数据 库 迁 移 的 migrations 目 录 以 及 中 
的 microblog. ea py 脚本 。 我 还 复制 了 一 个 新 文件 ，boot.sh， 我 将 在 下 面 讨论 它 。 


RUN chmod 命令 确保 将 这 个 新 的 boot.sh 文 件 正确 设置 为 可 执行 文件 。 如 果 你 使 用 的 是 基于 
Unix 的 文件 系统 ， 并 且 你 的 源 文件 已 被 标记 为 可 执行 文件 ， 则 复制 的 文件 将 会 已 是 可 执行 
的 。 我 显 式 地 对 其 进行 授权 ， 是 因为 在 Windows 上 很 难 设置 可 执行 位 。 如 果 你 正在 使 用 Mac 
OS X 或 Linux， 你 可 能 不 需要 这 个 步骤， 但 有 了 它 也 不 会 有 什么 问题 。 


ENV 命令 在 容器 中 设置 环境 变量 。 我 需要 设置 FLASK_APP ， 它 是 flask 命令 所 依赖 的 。 


下 面 的 RUN chown 命令 将 存储 在 /ommemmijicroblog 中 的 所 有 目录 和 文件 的 所 有 者 设置 为 新 

的 microblog 用 户 。 尽管 我 在 Dockerfile 的 顶部 附近 创建 了 该 用 户 ， 但 所 有 命令 的 默认 用 户 仍 
为 root ， 因 此 所 有 这 些 文件 的 属 主 都 需要 切换 到 microblog 用 户 ， 以 便 在 容器 局 动 时 该 用 户 
可 以 正确 运行 这 些 文件 。 


下 一 行 中 的 USER op 命令 使 得 这 个 新 的 microblog 用 户 成 为 任何 后 续 指 令 的 默认 用 户 ， 并 且 也 是 
容器 启动 时 的 默认 用 户 。 


EXPOSE A 该 容器 将 用 于 服务 的 端口 。 这 是 必要 的 ， 以 便 Docker 可 以 适当 地 在 容器 中 
配置 网 络 。 我 选择 了 标准 的 Flask 端 口 5000， 但 这 其 实 可 以 是 任意 端口 。 


aad > ENTRYPOINT 命令 定义 了 容器 启动 时 应 该 执行 的 默认 命令 。 这 是 启动 应 用 程序 Web 服 务 
器 的 命令 。 为 了 保持 ae ee eee 我 决定 为 此 创建 一 个 单独 的 脚本 ， 正 是 我 之 前 复 
sles 的 boot.sh 文 件 。 是 这 个 脚本 的 内 容 : 


boot.sh : Docker 容 器 启动 脚本 。 


#!/bin/sh 

source venv/bin/activate 

flask db upgrade 

flask translate compile 

exec gunicorn -b :5000 --access-logfile - --error-logfile - microblog:app 


这 是 一 个 相当 标准 的 启动 脚本 ， 与 第 十 七 齐 和 第 十 八 章 的 部 署 局 动 十 分 类 似 。 激活 虚拟 环 
境 ， 执 行 迁移 框架 升级 数据 库 ， 编 译 语言 翻译 ， 最 后 用 gunicorn 运 行 服 务 器 。 


请 注意 gunicorn 命 令 之 前 的 exec 。 在 shell 脚 本 中 ， exec 触发 正在 运行 脚本 的 进程 被 给 定 的 

Co 而 不 是 将 这 个 命令 作为 新 进程 启动 。 anh 因为 Docker 会 将 容器 的 生命 
与 其 上 运行 的 第 一 个 进程 关联 起 来 。 在 像 这 样 的 情况 下 ， 进程 不 是 容器 的 主 进程 ， 你 需 
要 确保 主 进程 取代 启动 进程 ， 以 确保 容器 不 会 提前 停止 。 


> 


Docker 的 一 个 有 趣 的 方面 是 容 器 写 入 stdout 或 stderr 的 任何 内 容 都 将 被 捕获 并 存储 为 容 容器 
的 日 志 。 出 于 这 个 原因 ， -access-logfile 和 --error-logfile 都 配置 为 - ， 它 将 日 ver 
标准 输出 ， 以 便 它 们 作为 日 志 由 Docker 存 储 。 


Dockerfile 写 好 后 ， 我 现在 可 以 构建 容器 镜像 了 : 


$ docker build -t microblog:latest . 


我 给 docker build 命令 的 -t 参数 设置 了 新 容器 镜像 的 名 称 和 标签 .表示 容器 构建 的 基础 
目录 ， 这 就 是 Dockerfile 所 在 的 目录 。 构建 过 程 将 执行 Dockerfile 中 的 所 有 命令 并 创建 镜像 ， 
该 镜像 将 存储 在 你 自己 的 机 器 上 。 


你 可 以 使 用 docker images 命令 获取 本 地 镜像 的 列表 : 


$ docker images 


REPOSITORY TAG IMAGE ID CREATED SIZE 
microblog latest 54a47d0c27cf About a minute ago 216MB 
python 3.6-alpine a6beab4fa70b 3 months ago 88.7MB 
mse 包含 你 的 新 镜像 以 及 它 的 基础 镜像 。 每 当 你 对 应 用 程序 进行 更 改 后 ， 都 可 以 通过 再 


[= 
尔 
次 运行 build 命 令 来 更 新 容器 镜像 。 


使 用 已 创建 的 镜像 ， 你 现在 可 以 运行 应 用 程序 的 容器 版 本 。 通过 docker run 命令 ， 通 常 再 搭 
配 大 量 的 参数 ， 就 可 以 完成 容器 的 启动 。 我 将 首先 向 你 展示 一 个 基本 的 例子 


$ docker run --name microblog -d -p 8000:5000 --rm microblog:latest 
021da2e1e0d390320248abf97dfbbe7b27c70fefedi113d5a41bb67a68522e91c 


--name 选项 为 新 容器 提供 了 一 个 名 称 。 -a 选项 告诉 Docker 在 后 台 运 行 容 

有 -d ， 容 器 将 作为 前 台 应 用 程序 运行 ， 从 而 阻塞 你 的 命令 提示 符 。 -p 选项 将 

到 主机 端口 。 第 一 个 端口 是 主机 上 的 端口 ， 右 边 的 端口 是 容器 内 的 端口 。 上 面 的 例子 暴露 了 

主机 端口 8000， 其 对 应 容器 中 的 端口 5000， 因 此 即使 内 部 容器 使 用 5000， 你 也 将 在 宿主 机 上 

访问 端口 8000 来 访问 应 用 程序 。 一 旦 容器 停止 ， --rm 选项 将 使 其 自动 被 删除 。 虽然 这 不 是 

roe ， 但 完成 或 中 断 的 容器 通常 不 再 需要 ， 因 此 可 以 自动 删除 。 最 后 一 个 参数 是 容器 使 用 
容器 镜像 名 称 和 标签 。 运行 上 述 命令 后 ， 可 以 在 http:/localhost:8000 上 访问 该 应 用 程 


+ 


docker run 的 输出 是 分 配给 新 容器 的 ID 。 这 是 一 个 很 长 的 十 六 进 制 字符 串 ， 在 随后 的 命令 中 
你 可 以 使 用 它 来 引用 。 实 际 上 ， 只 有 前 几 个 字符 是 必需 的 ， 足 以 保证 ID 的 唯一 性 。 


如 果 你 想 看 看 哪些 容器 正在 运行 ， 你 可 以 使 用 docker ps 命令 
$ docker ps 
CONTAINER ID IMAGE COMMAND PORTS NAMES 


021da2e1e0d3 microblog:latest "./boot.sh" 0.0.0.0:8000->5000/tcp microblog 


你 可 以 看 到 ， 其 实 docker ps 命令 显示 的 是 缩短 了 的 容器 ID。 如 果 你 现在 想 停 止 容器 ， 你 可 
以 使 用 docker stop 


$ docker stop 021da2e1e0d3 
021da2e1e0d3 


回顾 一 下 ， 应 用 程序 配置 中 有 许多 来 自 环境 变量 的 选项 。 例 如 ，Flask 密 钥 ， 数 据 库 URL 和 电 
子 邮 件 服务 器 选项 都 是 从 环境 变量 中 导入 的 。 在 上 面 的 docker run 例子 中 ， 我 没有 考虑 这 
些 ， 因 此 所 有 这 些 配 置 选 项 都 将 使 用 默认 值 。 


在 更 实际 的 例子 中 ， 你 将 在 容器 内 设置 这 些 环境 变量 。 你 在 前 面 的 章节 看 到 ，Dockerfile 中 的 
ENV 命 令 设置 了 环境 变量 ， 对 于 将 变 为 静态 的 变量 来 说 ， 这 是 一 个 方便 的 选项 。 但 是 ， 对 于 
依赖 于 安装 的 变量 ， 将 它们 作为 构建 过 程 的 一 部 分 并 不 方便 ， 因 为 你 希望 容器 镜像 具有 良好 
的 可 移植 性 。 如 果 你 想 将 应 用 程序 作为 容器 镜像 提供 给 另 一 个 人 ， 你 希望 该 人 员 能 够 按 原样 
使 用 它 ， 而 不 必 使 用 不 同 的 变量 重新 构建 它 。 


所 以 构建 时 的 环境 
境 变量 ， 对 于 这 些 


量 可 能 很 有 用 ， 但 是 也 需要 有 可 以 通过 docker run 命令 设置 的 运行 时 环 
量 ， 可 以 使 用 -e 选项 来 设置 。 以 下 示例 设置 了 密 钥 和 gmail 帐 户 : 


aa a 


$ docker run --name microblog -d -p 8000:5000 --rm -e SECRET_KEY=my-secret-key \ 
-e MAIL_SERVER=smtp.googlemail.com -e MAIL_PORT=587 -e MAIL_USE_TLS=true \ 
-e MAIL_USERNAME=<your -gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
microblog:latest 


由 于 具有 许多 环境 变量 定义 ， docker run 命令 行 非常 长 的 情况 并 不 罕见 。 


使 用 第 三 方 “容器 化 ”服务 


Microblog 的 容器 版 本 看 起 来 不 错 ， 但 我 还 没有 丨 正 考虑 过 很 多 关于 存储 的 问题 。 实 际 上 ， 由 
于 我 没有 设置 DATABASE_URL 环境 变量 ， 因 此 应 用 程序 正在 使 用 默认 SQLite 数 据 库 并 将 数据 存 
储 在 容器 内 部 的 文件 系统 上 。 当 你 停止 并 删除 容器 时 ， 你 认为 数据 去 哪里 了 ? 数据 也 会 被 删 
除 | 


容器 中 的 文件 系统 是 临时 的 ， 这 意味 着 它 随 着 容器 的 删除 而 删除 。 你 可 以 将 数据 写 入 容器 内 
的 文件 系统 ， 并 且 容 器 可 以 正常 读 写 数据 ， 但 如 果 出 于 任何 原因 需要 回收 容器 并 将 其 替换 为 
新 的 容器 ， 则 应 用 程序 保存 到 容器 内 的 任何 数据 将 永远 丢失 。 


容器 应 用 程序 的 一 个 好 的 设计 策略 是 保持 应 用 程序 容器 无 状态 。 如 果 你 的 应 用 程序 代码 和 数 
据 容 器 没有 任何 问题 ， 可 以 将 其 丢弃 并 替换 为 新 的 容器 ， 容 器 变 为 日 正 的 一 次 性 容器 ， 这 在 
简化 升级 部 署 方面 非常 有 用 。 


但 是 ， 这 意味 着 数据 必须 放 在 应 用 程序 容器 之 外 的 某 个 位 置 。 这 就 是 神奇 的 Docker 生 态 系统 
发 挥 作用 的 地 方 了 。 Docker 容 器 镜像 仓库 包含 大 量 的 容器 镜像 。 你 已 经 了 解 了 Python 容器 镜 
像 ， 我 正在 使 用 它 作为 我 的 Microblog 容 器 的 基础 镜像 。 除 此 之 外 ，Docker 还 为 Docker 容 器 

镜像 仓库 中 的 许多 其 他 语言 ， 数 据 库 和 其 他 服务 维护 镜像 ， 如 果 这 还 不 够 ，Docker 容 器 镜像 


仓库 还 允许 公司 为 其 产品 发 布 容器 镜像 ， 并 且 像 你 我 这 样 的 常规 用 户 也 可 以 发 布 自己 的 镜 
像 。 这 意味 着 安装 第 三 方 服务 需要 做 出 的 努力 会 减少 成 只 需 在 Docker 容 器 镜像 仓库 中 找到 合 
适 的 镜像 ， 并 通过 带 有 适当 参数 的 docker run 命令 启动 它 。 


所 以 我 现在 要 做 的 是 创建 两 个 额外 的 容器 ， 一 个 用 于 MySQL 数 据 库 ， 另 一 个 用 于 
Elasticsearch 服 务 ， 然 后 我 将 加 长 启动 Microblog 容 器 的 命令 ， 以 使 其 能 够 访问 这 两 个 新 的 容 
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添加 MySQL 容 器 


像 许 多 其 他 产品 和 服务 一 样 ，MySQL 在 Docker 镜 像 仓 库 中 提供 了 公共 容器 镜像 。 就 像 我 自己 
的 Microblog 容 器 一 样 ，MySQL 依 赖 于 需要 传递 给 docker run 的 环境 变量 。 他 们 配置 了 密 

码 ， 数 据 库 名 称 等 。 在 镜像 仓库 中 有 许多 MySQL 镜 像 时 ， 我 决定 使 用 由 MySQL 官 方 团队 维护 
的 镜像 。 你 可 以 在 其 镜像 仓库 页 面 找到 有 关 MySQL 容 器 镜像 的 详细 信 

息 : httos://hub.docker.com/r/mysqi/mysql-server/ ° 


回顾 一 下 在 第 十 七 章 中 设置 MySQL 的 繁琐 过 程 ， 你 就 会 赞叹 在 Docker 中 部 署 MySQL 的 轻松 体 
验 。 这 里 是 局 动 MySQL 服 务 器 的 docker run 命令 : 


$ docker run --name mysql -d -e MYSQL_RANDOM_ROOT_PASSWORD=yes \ 
-e MYSQL_DATABASE=microblog -e MYSQL_USER=microblog \ 
-e MYSQL_PASSWORD=<database-password> \ 
mysql/mysql-server:5.7 


这 就 对 了 | 在 安装 了 Docker 的 任何 机 器 上 ， 你 可 以 运行 上 面 的 命令 ， 就 会 得 到 一 个 完成 安装 
的 MySQL 服 务 器 ， 它 具有 一 个 随机 生成 的 root 密 码 ， 一 个 名 为 microblog 的 全 新 数据 库 和 一 


个 名 字 相 同 的 用 户 ， 该 用 户 具备 访问 这 个 数据 库 的 所 有 权限 。 请 注意 ， 你 需要 输入 正确 的 密 
码 ， 以 便 它 可 以 从 MYsQL_PASSWORD 环境 变量 获得 。 


现在 在 应 用 程序 方面 ， 我 需要 添加 一 个 MySQL 客 户 端 软件 包 ， 就 像 我 在 Ubuntu 上 进行 传统 部 
署 一 样 。 我 将 再 次 使 用 pymysql ， 我 可 以 将 它 添加 到 Dockerfile 中 : 


Dockerfile : 添加 pymysql 到 Dockerfile 中 。 


共计 
RUN venv/bin/pip install gunicorn pymysql 
# nn 


任何 时 候 对 应 用 程序 或 Dockerfile 进 行 更 改 后 ， 都 需要 重建 容器 镜像 : 


$ docker build -t microblog:latest . 


现在 我 可 以 再 次 启动 Microblog， 但 是 这 次 连接 到 数据 库容 器 ， 以 便 两 者 都 可 以 通过 网 络 进行 


通信 : 


$ docker run --name microblog -d -p 8000:5000 --rm -e SECRET_KEY=my-secret-key \ 
-e MAIL_SERVER=smtp.googlemail.com -e MAIL_PORT=587 -e MAIL_USE_TLS=true \ 
-e MAIL_USERNAME=<your -gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
--link mysql:dbserver \ 
-e DATABASE_URL=mysql+pymysql://microblog:<database-password>@dbserver/microblog \ 
microblog:latest 


--link 选项 告诉 Docker 让 正 要 运行 的 容器 可 以 访问 参数 中 指定 的 容器 。 该 参数 包含 由 冒号 

分 隔 的 两 个 名 称 。 第 一 部 分 是 要 链接 的 容器 的 名 称 或 ID， 在 本 例 中 是 我 在 上 面 创建 的 一 个 名 
为 mysql 的 容器 。 第 二 部 分 定义 了 一 个 可 以 在 这 个 容器 中 用 来 引用 链接 的 主机 名 。 这 里 我 使 
用 dbserver 作为 代表 数据 库 服务 器 的 通用 名 称 。 


通过 建立 两 个 容器 之 间 的 链接 ， 我 可 以 设置 DATABASE_URL 环境 变量 ， 以 便 SQLAIchemy 被 引 
导 使 用 其 他 容器 中 的 MySQL 数 据 库 。 数据 库 URL 将 使 用 dbserver 作为 数据 库 主机 
名 ， microblog 作为 数据 库 名 称 和 用 户 ， 以 及 你 在 局 启动 MySQL 时 选 择 的 密码 。 


我 在 试用 MySQL 容 器 时 注意 到 的 一 件 事 是 ， 这 个 容器 需要 几 秒 钟 才能 完全 运行 并 准备 好 接受 
数据 库 连 接 。 如 果 启 动 MySQL 容 器 ， 然 后 立刻 启动 应 用 容器 ， 在 boot.sh 脚 本 尝试 运 

行 flask db migrate 时 ， 则 可 能 会 因数 据 库 未 准备 好 接受 连接 而 失败 。 为 了 使 我 的 解决 方案 
更 加 健壮 ， 我 决定 在 boot.sh 中 添加 一 个 重 试 循环 : 


boot.sh : 重 试 数据 库 连 接 。 


#!/bin/sh 
source venv/bin/activate 
while true; do 

flask db upgrade 


if [[ Bs Sp 二 二 Ng" ae then 
break 
fi 
echo Upgrade command failed, retrying in 5 secs... 
sleep 5 
done 
flask translate compile 
exec gunicorn -b :5000 --access-logfile - --error-logfile - microblog:app 


此 循环 检查 flask db upgrade 命令 的 退出 代码 ， 如 果 它 不 为 零 ， 则 认为 出 现 了 问题 ， 因 此 它 
会 等 待 5 秒 钟 然后 重 试 。 
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#7 Elasticsearch& & 


Elasticsearch Docker 文 档 演 示 了 如 何 将 该 服务 作为 单一 节点 以 用 于 开发 模式 ， 以 及 部 署 两 个 
节点 的 生产 环境 服务 。 现 在， 我 将 使 用 单 节 点 模式 ， 并 使 用 引擎 开源 的 “oss" 镜 像 。 容器 使 用 
a 令 尼 动 : 


$ docker run --name elasticsearch -d -p 9200:9200 -p 9300:9300 --rm \ 
-e "discovery.type=single-node" \ 
docker.elastic.co/elasticsearch/elasticsearch-oss:6.1.1 


这 个 docker run 命令 与 我 用 于 Microblog 和 MySQL 的 命令 有 很 多 相似 之 处 ， 但 是 有 一 些 有 趣 
的 区 别 。 首先 ， 有 两 个 -p 选项 ， 这 意味 着 这 个 容器 将 在 两 个 端口 上 而 不 是 一 个 端口 上 进行 
监听 。 端口 92200 和 9300 都 映射 到 主机 中 的 相同 端口 。 


另 一 个 区 别 在 于 用 于 引用 容器 镜像 的 语法 。 对 于 我 在 本 地 构建 的 镜像 ， 语 法 

是 <name>:<tag> ° MySQL 容 器 使 用 格式 为 稍微 更 完整 的 <account>/<name>:<tag> 语法 ， 适 用 
于 在 Docker 镜 像 仓 库 中 引用 容器 镜像 。 我 使 用 的 Elasticsearch 镜 像 遵循 模 

式 <registry>/<account><name>:<tag> ， 其 中 包括 镜像 仓库 的 地 址 作为 第 一 个 组 件 。 此 语法 用 
于 未 托管 在 Docker 镜 像 仓 库 中 的 镜像 。 在 本 处 ，Elasticsearch 在 docker.elastic.co 上 运行 自己 
的 容器 镜像 仓库 服务 ， 而 不 是 使 用 由 Docker 维 护 的 主 镜像 仓库 。 


所 以 ， 现 在 我 已 经 启动 并 运行 了 Elasticsearch 服 务 ， 我 可 以 修改 Microblog 容 器 的 启动 命令 以 
创建 指向 它 的 链接 并 设置 Elasticsearch 服 务 URL : 


$ docker run --name microblog -d -p 8000:5000 --rm -e SECRET_KEY=my-secret-key \ 
-e MAIL_SERVER=smtp.googlemail.com -e MAIL_PORT=587 -e MAIL_USE_TLS=true \ 
-e MAIL_USERNAME=<your -gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
--link mysql:dbserver \ 
-e DATABASE_URL=mysqlt+pymysql://microblog:<database-password>@dbserver/microblog \ 
--link elasticsearch:elasticsearch \ 
-e ELASTICSEARCH_URL=http://elasticsearch:9200 \ 
microblog:latest 


运行 此 命令 之 前 ， 如 果 你 仍然 在 运行 Microblog 容 器 ， 请 先 停止 它 。 还 要 仔细 操作 来 为 数据 
设置 正确 的 密码 ， 并 让 Elasticsearch 服 务 的 参数 处 于 命令 中 的 恰当 位 置 。 


现在 你 应 该 可 以 访问 httpJMJocalhost8000 并 使 用 搜索 功能 。 如 果 你 遇 到 任何 错误 ， 可 以 通过 
查看 容器 日 志 来 对 其 进行 排查 。 你 很 可 能 希望 查看 Microblog 容 器 的 日 志 ， 其 中 将 显示 任何 
Python 堆栈 跟踪 : 


$ docker logs microblog 


Docker % 3 42,12 6 JE 


现在 我 已 经 在 Docker 上 使 用 三 个 容 
三 方 镜像 。 如 果 你 想 提供 自己 的 容 
获取 到 的 Docker 镜 像 仓库 中 。 


ws M 


3 来 运行 了 完整 的 应 用 程序 ， 其 中 两 个 容器 来 自 公 开 的 第 
镜像 给 其 他 人 ， 那 么 你 必须 将 它们 推送 到 任何 人 都 可 以 


ay 


要 访问 Docker 镜 像 仓库 ， 你 需要 转 到 https://hub.docker.com 并 为 自己 创建 一 个 帐户 。 确 保 你 
选择 一 个 你 喜欢 的 用 户 名 ， 因 为 这 将 用 于 你 发 布 的 所 有 和 镜像。 


为 了 能 够 从 命令 行 访问 你 的 账户 ， 你 需要 使 用 docker login 命令 登录 : 


$ docker login 


如 果 你 一 直 跟 随 我 的 引 导 ， 现在 你 的 计算 机 上 已 经 有 一 个 名 为 microblog:latest 的 镜像 存储 
在 本 地 。 为 了 能 够 将 这 个 镜像 推送 到 Docker 镜 像 仓库 中 ， 它 需要 重新 命名 以 包含 该 帐户 ， 正 
如 来 自 MySQL 的 镜像 。 这 是 通过 docker tag 命令 完成 的 : 


$ docker tag microblog:latest <your-docker-registry-account>/microblog: latest 


如 果 你 再 次 用 docker images 列 出 你 的 镜像 ， 你 会 看 到 两 个 Microblog 条 目 ， 一 个 
是 microblog:latest ， 另 一 个 还 包括 你 的 帐户 名 。 它们 实际 上 是 同一 镜像 的 两 个 别名 。 


要 将 镜像 发 布 到 Docker 镜 像 仓库 ， 请 使 用 docker push 命令 


$ docker push <your-docker-registry-account>/microblog: latest 


TEN 的 镜像 被 公开 了 ， 你 可 以 像 MySQL 和 服务 那样 ， 说 明 如 何 安装 它 并 从 Docker 镜 像 仓库 
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容器 化 应 用 的 部 羊 


让 你 的 应 用 程序 在 Docker 容 器 中 运行 的 最 大 的 好 处 之 一 是 ， 一 旦 该 容器 在 你 的 本 地 测试 通 

了 ， 就 可 以 将 它们 运行 到 任何 提供 Docker 支 持 的 平台 。 例如 ， 你 可 以 使 用 ， ee 
Digital Ocean，Linode 或 Amazon Lightsail 上 的 相同 服务 器 。 即使 这 些 提 供 商 提供 的 最 便宜 的 
产品 也 足以 让 Docker 运 行 一 些 容器 。 


Amazon Container Service (ECS) 使 你 能 够 创建 一 个 容器 宿主 机 集群 ， 以 在 其 中 运行 容 
o。 在 集成 完备 的 AWS 环 境 中 ， 提 供 了 水 平 扩展 和 负载 平衡 ， 以 及 为 容器 镜像 使 用 私有 容器 
镜像 仓库 的 功能 。 


最 后 ， 容 器 编排 平台 例如 Kubernetes 通 过 允许 你 以 简单 的 YAML 格 式 文 本 文件 描述 你 的 多 容器 
部 署 逻 辑 ， 来 提供 了 更 高 级 别 的 自动 化 和 便利 性 ， 负 载 均 衡 ， 水 平 扩 展 ， 密 钥 的 安全 管理 以 
及 滚动 升级 和 回 滚 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part XXI: User Notifications 


这 是 Flask Mega-Tutorial 系 列 的 第 二 十 一 章 ， 我 将 添加 一 个 私有 消息 功能 ， 它 将 在 导航 栏 中 显 
示 用 户 通知 ， 而 且 无 需 刷 新 页 面 就 可 以 自动 更 新 。 


在 本 章 中 ， 我 想 继续 致力 于 改进 Microblog 应 用 程序 的 用 户 体 验 。 有 一 个 广泛 应 用 的 功能 是 向 
用 户 显示 警报 或 通知 。 社交 应 用 通常 会 通过 在 顶部 导航 栏 中 显示 带 有 数字 的 小 徽章 显示 这 些 
通知 来 让 你 知道 有 新 的 提 及 (@) 或 私有 消息 。 虽然 这 是 最 明显 的 用 法 ， 但 通知 模式 还 可 以 
应 用 于 许多 其 他 类 型 的 应 用 程序 ， 以 通知 用 户 需 要 注意 的 事项 。 


为 了 向 你 展示 构建 用 户 通 知 所 涉及 的 技术 ， 我 需要 扩展 Microblog。 因 此 在 本 章 的 第 一 部 分 
中 ， 我 将 构建 一 个 用 户 消息 传递 系统 ， 它 允许 任何 用 户 发 送 私 有 消息 给 另 一 个 用 户 。 这 实际 


简单 ， 高 效 和 有 趣 的 方面 做 到 什么 程度 。 一旦 消息 系统 就 位 ， 我 就 会 讨论 一 些 方法 来 实现 显 
示 未 读 消息 计数 的 通知 标志 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 


私有 消息 


我 要 实现 的 私有 消息 功能 非常 简单 。 当 你 访问 用 户 的 个 人 主页 时 ， 会 显示 一 个 可 以 向 该 用 户 
发 送 私有 消息 链接 。 该 链接 将 带 你 进入 一 个 新 的 页 面 ， 在 新 页 面 中 ， 可 以 在 Web 表 单 中 发 送 
消息 。 要 阅读 发 送 给 你 的 消息 ， 页 面 顶部 的 导航 栏 将 会 有 一 个 新 的 “消息 "链接 ， 它 会 将 你 带 
到 与 主页 或 发 现 页 面相 似 的 页 面 ， 但 不 会 显示 用 户 动态 ， 它 会 显示 其 他 用 户 发 送 给 你 的 消 
息 。 


私有 消息 的 数据 库 支持 
第 一 项 任务 是 扩展 数据 库 以 支持 私有 消息 。 这 是 一 个 新 的 Message 模型 : 
app/models.py : Message 模 型 。 


class Message(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
sender_id = db.Column(db.Integer, db.Foreignkey('user.id')) 
recipient_id = db.Column(db.Integer, db.Foreignkey('user.id')) 
body = db.Column(db.String(140) ) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 


def _ repr_ (self): 
return '<Message {}>'.format(self.body) 


这 个 模型 类 与 post 模型 相似 ， 唯 一 的 区 别 是 有 两 个 用 户外 键 ， 一 个 用 于 发 信人 ， 另 一 个 用 于 
收 信人 。 User 模型 可 以 获得 这 两 个 用 户 的 关系 ， 以 及 一 个 新 字段 ， 用 于 指示 用 户 最 后 一 次 
阅读 他 们 的 私有 消息 的 时 间 : 


app/models.py : User 模 型 对 私有 消息 的 支持 。 


class User(UserMixin, db.Model): 
# on. 
messages_sent = db.relationship( 'Message', 
foreign_keys='Message.sender_id', 
backref='author', lazy='dynamic' ) 
messages_received = db.relationship('Message', 
foreign_keys='Message.recipient_id', 
backref='recipient', lazy='dynamic' ) 
last_message_read_time = db.Column(db.DateTime) 
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def new_messages(self): 
last_read_time = self.last_message_read_time or datetime(1900, 1, 1) 
return Message.query.filter_by(recipient=self).filter( 
Message.timestamp > last_read_time).count() 


这 两 个 关系 将 返回 给 定 用 户 发 送 和 接收 的 消息 ， 并 且 在 关系 的 message 一 侧 将 添 

加 author 和 recipient 回调 引用 。 我 之 所 以 使 用 author 回调 而 不 是 更 适合 的 sender ， 是 
因为 通过 使 用 author ， 我 可 以 使 用 我 用 于 用 户 动态 的 相同 逻辑 泻 梁 这些 消息 。 
last_message_read_time 字段 将 存储 用 户 最 后 一 次 访问 消息 页 面 的 时 间 ， 并 将 用 于 确定 是 否 有 
比 此 字段 更 新 时 间 戳 的 未 读 消 息 。 new_messages() 辅助 方法 实际 上 使 用 这 个 字段 来 返回 用 户 
有 多 少 条 未 读 消息 。 在 本 章 的 最 后 ， 我 将 把 这 个 数字 作为 页 面 顶 部 导航 栏 中 的 一 个 漂亮 的 徽 
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完成 了 数据 库 更 改 后 ， 现 在 是 时 候 生成 新 的 迁移 并 使 用 它 升 级 数据 库 了 : 


(venv) $ flask db migrate -m "private messages" 
(venv) $ flask db upgrade 


发 送 一 条 私有 消息 
下 一 步 设计 发 送 消息 。 我 需要 一 个 简单 的 Web 表 单 来 接收 消息 : 
app/main/forms.py : 私有 消息 表单 类 。 


class MessageForm(FlaskForm): 
message = TextAreaField(_1('Message'), validators=[ 
DataRequired(), Length(min=0, max=140)]) 
submit = SubmitField(_1('Submit' ) ) 


而 且 我 还 需要 在 网 页 上 呈现 此 表单 的 HTML 模 板 : 


app/templates/send_message.html : 发 送 私 有 消息 HTML 模 板 。 


{% extends "base.html" %} 
{% import 'bootstrap/wtf.html' as wtf %} 


{% block app_content %} 
<hi>{{ _('Send Message to %(recipient)s', recipient=recipient) }}</h1> 
<div class="row"> 
<div class="col-md-4"> 
{{ wtf.quick_form(form) }} 
</div> 
</div> 
{% endblock %} 


接 下 来 ， 我 将 添加 一 个 新 的 /send_message/ 路 由 来 处 理 实际 发 送 的 私有 消息 : 
app/main/routes.py : 发 送 私有 消息 的 视图 函数 。 


from app.main.forms import MessageForm 
from app.models import Message 


# ... 


@bp.route('/send_message/<recipient>', methods=['GET', 'POST']) 
@login_required 
def send_message(recipient): 
user = User.query.filter_by(username=recipient).first_or_404() 
form = MessageForm( ) 
if form.validate_on_submit(): 
msg = Message(author=current_user, recipient=user, 
body=form.message. data) 
db.session.add(msg) 
db.session.commit() 
flash(_('Your message has been sent.')) 
return redirect(url_for('main.user', username=recipient ) ) 
return render_template('send_message.html', title=_('Send Message'), 
form=form, recipient=recipient ) 


这 个 视图 函数 中 的 逻辑 显而易见 。 发 送 私 有 消息 的 操作 只 需 在 数据 库 中 添加 一 个 新 的 " 消 
息 "实例 即 可 。 


将 所 有 内 容 联系 在 一 起 的 最 后 一 项 更 改 是 在 用 户 个 人 主页 中 添加 上 述 路 由 的 链接 : 


app/templates/user.html : 个 人 主页 中 添加 发 送 私 有 消息 的 链接 。 


{% if user != current_user %} 
<p> 
<a href="{{ url_for('main.send_message', 
recipient=user.username) }}"> 
{{ _('Send private message') }} 
</a> 
</p> 
{% endif %} 


查看 私有 消息 


这 个 功能 的 第 二 大 部 分 是 查看 私有 信息 。 为 此 ， 我 添加 另 一 条 路 由 /messages， 该 路 由 与 主 
页 和 发 现 页 面 非常 相似 ， 包 括 分 页 的 完全 支持 : 


app/main/routes.py : 查看 消息 视图 函数 。 


@bp.route('/messages' ) 
@login_required 
def messages(): 
current_user.last_message_read_time = datetime.utcnow( ) 
db.session. commit () 
page = request.args.get('page', 1, type=int) 
messages = current_user.messages_received.order_by( 
Message. timestamp.desc()).paginate( 
page, current_app.config['POSTS_PER_PAGE'], False) 
next_url = url_for('main.messages', page=messages.next_num) \ 
if messages.has_next else None 
prev_url = url_for('main.messages', page=messages.prev_num) \ 
if messages.has_prev else None 
return render_template('messages.html', messages=messages.items, 
next_url=next_url, prev_url=prev_ur1) 


我 在 这 个 视图 函数 中 做 的 第 一 件 事 是 用 当前 时 间 更 新 user.last_message_read_time 字段 。 这 
会 将 发 送 给 该 用 户 的 所 有 消息 标记 为 已 读 。 然后 ， 我 查询 消息 模型 以 获得 消息 列表 ， 并 按照 
最 近 的 时 间 改 进行 排序 。 我 决定 在 这 里 复 用 posts_per pace 配置 项 ， 因 为 用 户 动 态 和 消息 的 
页 面 看 起 来 非常 相似 ， 但 是 如 果 发 生 了 分 歧 ， 为 消息 添加 单独 的 配置 变量 也 是 有 意义 的 。 分 
页 逻辑 与 我 用 于 用 户 动态 的 逻辑 完全 相同 ， 因 此 这 对 你 来 说 应 该 很 熟悉 。 


上 面 的 视图 叉 数 通过 泻 染 一 个 新 的 /app/emplates 人 messages.htm/ 模 板 文件 结束 ， 该 模板 如 
下 


app/templates/messages.html : 查看 消息 HTML 模 板 。 


{% extends "base.html" %} 


{% block app_content %} 
<hi>{{ _('Messages') }}</h1> 
{% for post in messages %} 
{% include '_post.html' %} 
{% endfor %} 
<nav aria-label="..."> 
<ul class="pager"> 
<li class="previous{% if not prev_url %} disabled{% endif %}"> 
<a href="{{ prev_url or '#' }}"> 
<span aria-hidden="true">&larr;</span> {{ _('Newer messages') }} 
</a> 
</li> 
<li class="next{% if not next_url %} disabled{% endif %}"> 
<a href="{{ next_url or '#' }}"> 
{{ _('Older messages') }} <span aria-hidden="true">&rarr;</span> 
</a> 
</li> 
</ul> 
</nav> 
{% endblock %} 


ERE’ RARITA- © 我 注意 到 除了 message 具有 额外 的 recipient KA (我 不 
需要 在 消 息 页 面 中 显示 ， 因 为 它 总 是 当 前 用 户 ) ， Post 和 Message 实例 具有 几乎 相 同 的 结 
构 。 所 以 我 决定 复 用 app/templates/_post.html 子 模板 来 演 染 私有 消息 。 出 于 这 个 原因 ， 这 个 
模板 使 用 了 奇怪 的 for 循 环 for post in messages ， 以 便 私 有 消息 的 泻 当 也 可 以 套用 到 子 模板 
Ea 


要 让 用 户 访问 新 的 视图 函数 ， 导 航 页 面 需要 生成 一 个 新 的 "消息 "链接 : 
app/templates/base.html : 导航 栏 中 的 消息 链接 。 


{% if current_user.is_anonymous %} 


{% else %} 
<li> 
<a href="{{ url_for('main.messages') }}"> 


{{ _('Messages') }} 
</a> 
</li> 


{% endif %} 


该 功能 现 已 完成 ， 但 作为 所 有 更 改 的 一 部 分 ， St ， 并 且 需 
要 将 这 些 文本 合并 到 语言 翻译 中 。 第 一 步 是 更 新 所 有 的 语言 目录 


(venv) $ flask translate update 


然后 ，app/translations 中 的 每 种 语言 都 需要 使 用 新 翻译 更 新 其 messages.po 文 件 。 你 可 以 在 
本 项 目的 GitHub 代 码 库 中 找到 西班牙 语 翻 译 ， 或 者 直接 下 载 Zip 文 件 。 


静态 消息 通知 和 Ao 


现在 私有 消息 功能 已 经 实现 ， 但 是 还 没有 通过 任何 渠道 告诉 用 户 有 私有 消息 等 待 阅读 。 导 航 
栏 上 的 未 读 消息 标志 的 最 简单 实现 可 以 使 用 Bootstrap badge 小 部 件 泻 染 到 基础 模板 中 : 


app/templates/base.html : 导航 栏 的 静态 消息 通知 徽章 。 


<li> 
<a href="{{ url_for('main.messages') }}"> 
{{ _('Messages') }} 
{% set new_messages = current_user.new_messages() %} 
{% if new_messages %} 
<span class="badge">{{ new_messages }}</span> 
{% endif %} 
</a> 
</li> 


ee 我 直接 从 模板 中 调用 上 面 添加 到 User 模 型 中 的 new _messages() 方法 ， 并 将 该 数字 存 
TAE new messages 模板 变量 中 。 然后 ， 如 果 该 变量 不 为 零 ， 我 只 需 添 加 带 有 该 数字 的 徽章 到 
消息 链接 后 面 即 可 。 以 下 是 这 个 页 面 的 外 观 : 


Microblog Home Explore | Messages Œ) Profile Logout 


动态 消息 通知 徽章 


上 一 节 介 绍 的 解决 方案 是 一 种 简单 的 常规 方式 来 显示 通知 ， 但 它 有 一 个 缺点 ， 即 徽章 仅 在 加 
载 新 页 面 时 刷新 。 如 果 用 户 花费 很 长 时 间 阅 读 一 个 页 面 上 的 内 容 而 没有 点 击 任何 链接 ， 那 么 
在 该 时 间 内 出 现 的 新 消息 将 不 会 显示 ， 直 到 用 户 最 终点 击 链接 并 加 载 新 页 面 。 


为 了 让 这 个 应 用 程序 对 我 的 用 户 更 有 用 ， 我 希望 徽章 自行 更 新 未 读 消息 的 数量 ， 而 用 户 不 必 
点 击 链接 并 加 载 新 页 面 。 上 一 节 的 解决 方案 的 一 个 问题 是 ， 当 加 载 页 面 时 消息 计数 为 非 零 
时 ， 徽 章 才 在 页 面 中 党 染 。 更 方便 的 是 始终 在 导航 栏 中 包含 徽章 ， 并 在 消息 计数 为 零 时 将 其 
标记 为 隐藏 。 这 样 可 以 很 容易 地 使 用 JavaScript 显 示 徽 章 : 


app/templates/base.html : 使 用 JavaScript 演 染 的 友好 未 读 消 息 徽章 。 


<li> 
<a href="{{ url_for('main.messages') }}"> 
{{ _('Messages') }} 
{% set new_messages = current_user.new_messages() %} 
<span id="message_count" class="badge" 
style="Visibility: {% if new_messages %}visible 
{% else %}hidden {% endif %};"> 
{{ new_messages }} 
</span> 
</a> 
</li> 


使 用 此 版 本 的 徽章 时 ， 我 总 是 将 其 包含 在 内 ， 但 当 new_messages 非 零 时 ， visibility CSS 
属性 设置 为 visible ; 否则 设置 为 hidden 。 我 还 为 表示 徽章 的 元 素 添加 了 一 个 id 属性 ， 以 
便 使 用 $('#message_count' ) jQuery 选择 器 来 简化 这 个 元 素 的 选取 。 


接 下 来 ， 我 编写 一 个 简短 的 JavaScript 函 数 ， 将 该 徽章 更 新 为 最 新 的 数字 : 


app/templates/base.html : 导航 栏 中 的 动态 消息 通知 徽章 


{% block scripts %} 
<script> 
/A 
function set_message_count(n) { 
$('#message_count').text(n); 
$('#message_count').css('visibility', n ? 'visible' : 'hidden'); 


</script> 
{% endblock %} 


这 个 新 的 set_message_count() 函数 将 设置 徽章 元 素 中 的 消 息 数 量 2 并 调 整 可 见 性 ， 以 便 在 计 
数 为 0 时 隐藏 徽章 。 


现在 剩 下 的 就 是 增加 一 种 机 制 ， 通 过 这 种 机 制 ， 客 户 端 可 以 定期 接收 有 关 用 户 拥 有 的 未 读 消 
息 数 量 的 更 新 。 当 更 新 发 生 时 ， 客户 端 将 调用 set_message_count() Hiki N P Fea LB © 


实际 上 有 两 种 方法 可 以 让 服务 器 将 这 些 更 新 告知 客户 端 ， 而 且 你 可 能 会 猜 到 ， 这 两 种 方法 都 
有 优点 和 缺点 ， 因 此 选择 哪 种 方法 很 大 程度 上 取决 于 项 目 。 在 第 一 种 方法 中 ， 客 户 端 通过 发 
送 异步 请 求 定期 向 服务 器 请 求 更 新 。 来 自 此 请 求 的 响应 是 更 新 列表 ， 客 户 端 可 以 使 用 这 些 更 
新 来 更 新 页 面 的 不 同 元 素 ， 例 如 未 读 消息 计数 标记 。 第 二 种 方法 需要 客户 端 和 服务 器 之 间 的 
特殊 连接 类 型 ， 以 允许 服务 器 自由 地 将 数据 推送 到 客户 端 。 请 注意 ， 无 论 杀 用 哪 种 方法 ， 我 
都 希望 将 通知 视 为 通用 实体 ， 以 便 我 可 以 扩展 此 框架 以 支持 除 未 读 消息 徽章 以 外 的 其 他 类 型 
的 事件 。 


第 一 种 解决 方案 最 大 的 优点 是 易于 实施 。 我 需要 做 的 只 是 向 应 用 程序 添加 另 一 条 路 由 ， 例 
如 /notifications， 它 返回 JSON 格 式 的 通知 列表 。 然 后 客户 端 应 用 程序 遍历 通知 列表 并 将 必要 
的 更 改 应 用 于 页 面 。 该 解决 方案 的 缺点 是 实际 事件 和 通知 之 间 会 有 延迟 ， 因 为 客户 端 会 定期 
请 求 通知 列表 。 例如 ， 如 果 客 户 端 每 10 秒 钟 询问 一 次 通知 ， 则 可 能 延迟 10 秒 接收 通知 。 


第 二 个 解决 方案 需要 在 协议 级 别 进 行 更 改 ， 因 为 HTTP 没 有 服务 器 主动 向 客户 端 发 送 数据 的 任 
何 规定 。 到 目前 为 止 ， 实 现 服务 器 推送 消息 的 最 常见 方式 是 扩展 服务 器 以 支持 除 HTTP 之 外 的 
WebSocket 连 接 。 WebSocket 是 一 种 不 同 于 HTTP 的 协议 ， 在 服务 器 和 客户 端 之 问 建立 永久 
连接 。 服 务 器 和 客户 端 可 以 随时 向 对 方 发 送 数 据 ， 而 无 需 另 一 方 请 求 。 这 种 机 制 的 优点 是 ， 
无 论 何 时 发 生 客户 感 兴趣 的 事件 ， 服 务 器 都 可 以 发 送 通知 ， 而 不 会 有 任何 延迟 。 缺 点 是 
WebSocket 需 要 比 HTTP 更 复杂 的 设置 ， 因 为 服务 器 需要 与 每 个 客户 端 保持 永久 连接 。 想 象 一 
下 ， 例 如 有 四 个 worker 进 程 的 服务 器 通常 可 以 服务 几 百 个 HTTP 客 户 端 ， 因 为 HTTP 中 的 连接 
是 短暂 的 并 且 不 断 被 回收 。 而 相同 的 服务 器 只 能 处 理 四 个 WebSocket 客 户 端 ， 在 绝 大 多 数 情 
况 下 ， 这 会 导致 资源 紧张 。 正 是 由 于 这 种 限制 ，VVebSocket 应 用 程序 通常 围绕 异步 服务 器 进 
行 设 计 ， 因 为 这 种 服务 器 在 管理 大 量 worker 和 活动 连接 方面 效率 更 高 。 


好 消息 是 ， 不 管 你 使 用 什么 方法 ， 在 客户 端 你 都 会 有 一 个 回调 函数 ， 它 将 被 更 新 列表 调用 。 

因此 ， 我 可 以 从 第 一 个 解决 方案 开始 ， 该 解决 方案 实施 起 来 要 容易 得 多 ， 如 果 发 现 不 足 ， 可 
以 迁移 到 WebSocket 服 务 器 ， 该 服务 器 可 以 配置 为 调用 相同 的 客户 端 回调 。 在 我 看 来 ， 对 于 
这 种 类 型 的 应 用 ， 第 一 种 解决 方案 实际 上 是 可 以 接受 的 。 基 于 WebSocket 的 实现 对 于 需要 以 
接近 零 延 退 传递 更 新 的 应 用 程序 非常 有 用 。 


这 里 有 一 些 业界 的 类 似 案 例 。Twitter 也 使 用 的 是 第 一 种 导航 栏 通知 的 方法 ; Facebook 使 用 称 
为 长 轮 询 的 HTTP 变 体 ， 它 解决 了 直接 轮 询 的 一 些 限 制 ， 同 时 仍然 使 用 HTTP 请 求 ; Stack 
Overflow 和 Trello 这 两 个 站 点 使 用 WebSocket 来 实现 通知 机 制 。 你 可 以 通过 查看 浏览 器 调试 器 
的 “Network" 选 项 卡 来 查找 任何 网 站 上 发 生 的 后 台 活 动 请 求 。 


我 们 继续 实施 轮 询 解决 方案 。 首先 ， 我 要 添加 一 个 新 模型 来 跟踪 所 有 用 户 的 通知 ， 以 及 用 户 
模型 中 的 关系 。 


a 


app/models.py : 通知 模型 。 


import json 
from time import time 


# ... 


class User(UserMixin, db.Model): 
# ... 
notifications = db.relationship('Notification', backref='user', 
lazy='dynamic' ) 


# ... 


class Notification(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String(128), index=True) 
user_id = db.Column(db.Integer, db.ForeignkKey('user.id')) 
timestamp = db.Column(db.Float, index=True, default=time) 
payload_json = db.Column(db.Text) 


def get_data(self): 
return json. loads(str(self.payload_json) ) 


通知 将 会 有 一 个 名 称 ， 一 个 关联 的 用 户 ， 一 个 Unix 时 间 惟 和 一 个 有 效 载荷 。 时 间 改 默认 

从 time.time() 函数 中 获取 。 每 种 类 型 的 通知 都 会 有 所 不 同 ， 所 以 我 将 它 写 为 JSON 字 符 串 ， 
因为 这 样 可 以 编写 列表 ， 字 典 或 单个 值 (如 数字 或 字符 串 ) 。 为 了 方便 ， 我 添加 

了 get_data() 方法 ， 以 便 调 用 者 不 必 操 心 JSON 的 反 序 列 化 。 


这 些 更 改 需要 包含 在 新 的 数据 库 迁 移 中 : 


(venv) $ flask db migrate -m "notifications" 
(venv) $ flask db upgrade 


为 了 方便 ， 我 将 新 增 的 Message 和 Notification 模型 添加 到 Shell 上 下 文 ， 这 样 我 就 可 以 直接 
在 用 flask shell 命令 启动 的 解释 器 中 使 用 这 两 个 模型 了 。 


microblog.py: 添加 Message 和 Notification 模 型 到 shell 上 下 文 。 


# ,,， 
from app.models import User, Post, Notification, Message 


# wn. 
@app.shell_context_processor 
def make_shell_context(): 


return {'db': db, 'User': User, 'Post': Post, 'Message': Message 
"Notification': Notification} 


我 还 将 在 用 户 模 型 中 添加 一 个 add_notification() 辅助 方法 ， 以 便 更 轻松 地 处 理 这 些 对 象 : 


app/models.py : Notification 模 型 。 


class User(UserMixin, db.Model): 
He 


def add_notification(self, name, data): 
self.notifications.filter_by(name=name).delete() 
n = Notification(name=name, payload_json=json.dumps(data), user=self) 
db.session.add(n) 
return n 


AFETA M P US oi ko E> IRA Ro RA HAZ Ah he LR WASH AM 
除 该 通知 。 我 将 要 使 用 的 通知 将 被 称 为 unread_message_count ° 如 果 数 据 库 已 经 有 一 个 带 有 
这 个 名 称 的 通知 ， 例 如 值 为 3， 则 当 用 户 收 到 新 消息 并 且 消 息 计 数 变 为 4 时 ， 我 就 会 蔡 换 昌 的 


通知 。 


在 任何 未 读 消息 数 改 变 的 地 方 ， 我 需要 调用 add_notification() ， 以 便 我 更 新 用 户 的 通知 ， 
这 样 的 地 方 有 两 处 。 首先 ， 在 send_message() 视图 函数 中 > SAP 收 到 一 个 新 的 私有 消 息 
时 : 


app/main/routes.py : 更 新 用 户 通知 。 


@bp.route('/send_message/<recipient>', methods=['GET', 'POST']) 
@login_required 
def send_message(recipient): 

# 


if form.validate_on_submit(): 
# .,， 

user .add_notification('unread_message_count', user.new_messages() ) 

db.session.commit() 

# a. 


第 二 个 地 方 是 用 户 转 到 消息 页 面 时 ， 未 读 计数 需要 皮 零 : 
app/main/routes.py : 查看 消息 视图 函数 。 


@bp.route('/messages') 

@login_required 

def messages(): 
current_user.last_message_read_time = datetime.utcnow( ) 
current_user.add_notification('unread_message_count', 0) 
db.session.commit() 
# oa 


既然 用 户 的 所 有 通知 都 保存 在 数据 库 中 ， 那 么 我 可 以 添加 一 条 新 路 由 ， 客 户 端 可 以 使 用 该 路 
由 为 登录 用 户 检索 通知 : 


app/main/routes.py : #70 ALA Ba o 


from app.models import Notification 
# ..， 


@bp.route('/notifications') 
@login_required 
def notifications(): 
since = request.args.get('since', 0.0, type=float) 
notifications = current_user.notifications.filter( 
Notification.timestamp > since).order_by(Notification.timestamp.asc()) 
return jsonify([{ 
'name': n.name, 
'data': n.get_data(), 
'timestamp': n.timestamp 
} for n in notifications] ) 


这 是 一 ee tn pe ei 
三 个 元 素 的 字典 的 形式 给 出 ， 即 通知 名 称 ， 与 通知 有 关 的 附加 数据 (如 消息 数量 ) 和 时 间 
。 通知 按 e r AN o 


我 不 希望 客户 重复 发 送 a 合 他 们 提供 了 一 个 选项 ， 只 请 求 给 定时 间 惟 之 后 产生 的 
通知 。 since 选项 可 以 作为 浮 点 数 包 含 在 请 求 URL 的 查询 字符 串 中 ， 其 包含 开始 时 间 的 
unix 时 间 戳 。 如 果 包 含 此 参数 ， 则 知 才 会 被 返 


完成 此 功能 的 最 后 一 部 分 是 在 客户 端 实现 实际 轮 询 。 最 好 的 做 法 是 在 基础 模板 中 实现 ， 以 便 
所 有 页 面 自 动 继承 该 行为 : 


app/templates/base.html : 轮 询 通知 


{% block scripts %} 
<script> 
UU x60 
{% if current_user.is_authenticated %} 
$(function() { 
var since = 0; 
setInterval(function() { 
$.ajax('{{ url_for('main.notifications') }}?since=' + since) .done( 
function(notifications) { 
for (var i = 0; i < notifications.length; i++) { 
if (notifications[i].name == 'unread_message_count' ) 
set_message_count(notifications[i].data); 
since = notifications[i].timestamp; 


a 
}, 10000) ; 


3); 
{% endif %} 
</script> 


该 函数 包含 在 一 个 模板 条 件 中 ， 因 为 我 只 想 在 用 户 登录 时 轮 询 新 消息 。 对 于 没有 登录 的 用 
户 ， 这 个 函数 将 不 会 被 泻 染 。 


你 已 经 在 第 二 十 章 中 看 到 了 jQuery 的 $(function) { ...}) 模式 。 这 是 注册 一 个 函数 在 页 面 
加 载 后 执行 的 方式 。 对 于 这 个 功能 ， 我 需要 在 页 面 加 载 时 做 的 是 设置 一 个 定时 器 来 获取 用 户 
的 通知 。 你 还 看 到 了 setTimeout() JavaScript 部 数 ， 它 在 等 待 特 定时 间 之 后 运行 作为 参数 给 


出 的 函数 。 setInterval() 函数 使 用 与 setTimeout() 相同 的 参数 ， 但 不 是 一 次 性 触发 定时 
器 ， 而 是 定期 调用 回调 函数 。 本 处 ， 我 的 间隔 设置 为 10 秒 〈 以 毫秒 为 单位 ) ， 所 以 我 将 以 每 
分 钟 大 约 六 次 的 频率 查看 通知 是 否 有 更 新 。 


利用 定期 计时 器 和 Ajax， 该 函数 轮 询 新 通知 路 由 ， 并 在 其 完成 回调 中 和 迭代 通知 列表 。 当 收 到 
名 为 unread _message_count 的 通知 时 ， 通 过 调用 上 面 定 义 的 函数 和 通 知 中 给 全 出 的 计数 来 调整 消 
息 计 数 徽 章 。 


RAF since 参数 的 方式 可 能 会 令 人 困惑。 我 首先 将 这 个 参数 初始 化 为 0。 参数 总 是 包含 在 
请 求 URL 中 ， 但 是 我 不 能 像 以 前 那样 使 用 Flask 的 uri for) 来 生成 查询 字符 串 ， 因 为 一 次 请 
求 中 url_for() 只 在 服务 器 上 运行 一 次 ， 而 我 需要 since 参数 动态 更 新 多 次 2 第 一 次 ， 这 个 

请 求 将 被 发 送 到 /notifications?since=0， 但 是 一 旦 我 收 到 通知 ， 我 就 会 将 since 更 新 为 它 的 时 
间 稚 。 这 可 以 确保 我 不 会 收 到 重复 的 内 容 ， 因 为 我 总 是 要 求 收 到 自我 上 次 看 到 的 通知 以 来 发 
生 的 新 通知 。 同样 重要 的 是 要 注意 ， 我 在 interval 函 数 外 声明 since 变量 ， 因 为 我 不 希望 它 是 
局 部 变量 ， 我 想 要 在 所 有 调用 中 使 用 相同 的 变量 。 


最 简单 的 测试 方法 是 使 用 两 种 不 同 的 浏览 器 A 和 B。 在 两 个 浏览 器 上 使 用 不 同 的 用 户 登录 
。 然后 从 A 浏览 器 向 B 浏 览 器 上 的 用 户 发 送 一 个 或 多 个 消息 。B 浏 览 器 的 导航 栏 应 更 
新 为 显示 你 在 10 秒 钟 内 发 送 的 消息 数量 。 而 当 你 点 击 消息 链接 时 ， 未 读 消息 数 重 置 为 零 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part XXII: Background Jobs 


这 是 Flask Mega-Tutorial 系 列 的 第 二 十 二 部 分 ， 我 将 告诉 你 如 何 创建 独立 于 Web 服 务 器 之 外 运 
j 的 后 台 作 业 。 


本 章 致力 于 为 应 用 程序 中 运行 时 间 较 长 或 复杂 的 异步 任务 进程 进行 优化 。 这 些 进程 不 能 在 请 
求 的 上 下 文中 同步 执行 ， 因 为 这 会 在 任务 持续 期 间 阻 塞 对 客户 端的 响应 。 在 第 十 章 中 ， 我 将 
邮件 的 发 送 转移 到 后 台 线 程 中 执行 ， 以 免 阻 塞 响 应 。 虽然 使 用 线程 处 理 电 子 邮 件 是 可 以 接受 
的 ， 但 当 问 题 处 理 时 间 更 长 时 ， 此 解决 方案 就 不 足以 支撑 了 。 公认 的 做 法 是 将 耗 时 长 的 任务 
移交 到 worker 进 程 (或 进程 池 ) 。 

为 了 证 明 长 时 间 运 行 任务 存在 的 必要 性 ， 我 将 介绍 Microblog 的 一 个 导出 功能 ， 用 户 通 过 它 可 
ce 
ws 含 所 有 用 户 动 态 的 JSON 文 件 ， 然 后 通过 电子 邮件 发 送 给 


。 所 有 这 些 活动 都 将 在 worker 进 程 中 发 生 ， 并 且 在 执行 时 ， T 
a 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 
任务 队列 简介 


任务 队列 为 后 台 作 业 提 供 了 一 个 便捷 的 解决 方案 。 Worker 进 程 独立 于 应 用 程序 运行 ， 甚 至 可 
以 位 于 不 同 的 统 上 。 应 ee 的 通信 是 通过 消息 队列 完成 的 。 o 

















作业 ， 然 后 通过 与 队列 交互 来 监视 其 进度 。 下 图 展示 了 一 个 典型 的 实现 : 
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Python 中 最 流行 的 任务 队列 是 Celery。 这 是 一 个 相当 复杂 的 软件 包 ， 它 有 很 多 选项 并 支持 多 
个 消息 队列 。 另 一 个 流行 的 Python 任务 队列 是 Redis Queue(RQ)， 它 牺牲 了 一 些 灵活 性 ， 比 
如 只 支持 Redis 消 息 队 列 ， 但 作为 交换 ， 它 的 建立 要 比 Celery 简 单 得 多 。 


Celery 和 RQ 都 非常 适合 在 Flask 应 用 程序 中 支持 后 台 任 务 ， 所 以 我 倾向 于 选择 更 简单 的 RQ。 
不 过 ， 用 Celery 实 现 相 同 的 功能 其 实 也 不 难 。 如 果 你 对 Celery 更 感 兴趣 ， 可 以 阅读 我 的 博客 
中 的 Using Celery with Flask 文 章 。 


使 用 RQ 
RQ 是 一 个 标准 的 Python 三 方 软件 包 ， 用 pip 安装 : 


(venv) $ pip install rq 
(venv) $ pip freeze > requirements.txt 


正如 我 前 面 提 到 的 ， 应 用 和 RQ worker 之 问 的 通信 将 在 Redis 消 息 队 列 中 执行 ， 因 此 你 需要 运 
行 Redis 服 务 器 。 有 许多 途径 来 安装 和 运行 Redis 服 务 器 ， 比 如 下 载 其 源码 并 执行 编译 和 安 
装 。 如 果 你 使 用 的 是 Windows，Microsoft 在 此 处 维护 了 Redis 的 安装 程序 。 在 Linux 上 ， 你 可 
以 通过 操作 系统 的 软件 包 管 理 器 安装 Redis。 Mac OS X 用 户 可 以 运行 brew install redis ， 
然后 使 用 redis-server 命令 手动 启动 服务 。 


除了 确保 服务 正在 运行 并 可 供 RQ 访 问 之 外 ， 你 不 需要 与 Redis 进 行 其 他 交互 。 


创建 任务 


通过 RQ 执 行 一 项 简单 的 任务 后 ， 你 就 会 很 快 熟悉 它 。 一 个 任务 ， 不 过 是 一 个 Python 函数 而 
已 。 以 下 是 一 个 示例 任务 ， 我 将 其 放 入 一 个 新 的 app/tasks.py 模 块 : 


app/tasks.py : 示例 后 台 任 务 。 


Import time 


def example(seconds): 
print('Starting task') 
for i in range(seconds): 
print(i) 
time.sleep(1) 
print('Task completed’ ) 


该 任务 将 秒 数 作 为 参数 ， 然 后 在 该 时 间 量 内 等 待 ， 并 每 秒 打印 一 次 计数 器 。 
运行 RQ Worker 
任务 准备 就 绕 ， 可 以 通过 rq worker 来 启动 一 个 Worker 进 程 了 : 


(venv) $ rq worker microblog-tasks 

18:55:06 RQ worker 'rq:worker:miguelsmac.90369' started, version 0.9.1 
18:55:06 Cleaning registries for queue: microblog-tasks 

18:55:06 

18:55:06 *** Listening on microblog-tasks... 


Worker 进 程 现在 连接 到 了 Redis， 并 在 名 为 microblog-tasks 的 队列 上 查看 可 能 分 配给 它 的 任 
何 作 业 。 如 果 你 想 局 动 多 个 worker 来 扩展 乔 吐 量 ? 你 只 需要 运行 rq worker 来 生成 更 多 连接 
到 同一 个 队列 的 进程 。 然 后 ， 当 作业 出 现在 队列 中 时 ， 任 何 可 用 的 worker 进 程 都 可 以 获取 
它 。 在 生产 环境 中 ， 你 可 能 希望 至 少 运行 可 用 CPU 数量 的 worker。 


执行 任务 


现在 打开 第 二 个 终端 窗口 并 激活 虚拟 环境 。 我 将 使 用 Shell 会 话 来 启动 Worker 中 
的 example() 任务 


>>> from redis import Redis 

>>> import rq 

>>> queue = rq.Queue('microblog-tasks', connection=Redis.from_url('redis://')) 
>>> job = queue.enqueue('app.tasks.example', 23) 

>>> job.get_id() 

"c651de7f -21a8 -4068-afd5-8b982a6f6d32' 


来 自 RQ 的 queue 类 表示 从 应 用 程序 端 看 到 的 任务 队列 。 它 采 用 的 参数 是 队列 名 称 和 一 
个 redis 连接 对 象 ， 本 处 使 用 默认 URL 进 行 初 始 化 。 如 果 你 的 Redis 服 务 器 运行 在 不 同 的 主 
机 或 端口 号 上 ， 则 需要 使 用 其 他 URL 。 


Queue 的 enqueue() 方法 用 于 将 作业 添加 到 队列 中 a 第 一 个 参数 是 要 执行 的 任务 的 名 称 ， 可 
直接 传 入 函数 对 象 或 导入 字符 串 。 我 发 现 传 入 字符 串 更 加 方便 ， 因 为 不 需要 在 应 用 程序 的 一 
端 导 入 函数 。 对 enqueue() 传 入 的 任何 剩余 参数 将 被 传递 给 worker 中 运行 的 函数 。 


只 要 进 行 了 enqueue() 调用 ， 运行 着 RQ worker 的 终端 窗口 上 就 会 出 现 一 些 活动 ey 你 会 看 

到 example() 元 数 正在 运行 ， 并 且 每 秒 打印 一 次 计数 器 。 同 时 ， 你 的 其 他 终端 不 会 被 阻塞 ， 
你 可 以 继续 在 shell 中 执行 表达 式 。 在 上 面 的 例子 中 ， 我 调用 job.get_id() 方法 来 获取 分 配给 
任务 的 唯一 标识 符 。 你 可 以 尝试 使 用 另 一 个 有 趣 表 达 式 来 检查 Worker 上 的 函数 是 否 已 完成 : 


>>> job.is_finished 
False 


如 果 你 像 我 在 上 面 的 例子 中 那样 传递 了 23 > MABRY BINA o AMZ 
K > job.is finished 表达 式 将 变 为 True 。 就 是 这 么 简单 ， 炫 酷 否 ? 


一 旦 函数 完成 ，worker 又 回 到 等 待 作业 的 状态 ， 所 以 如 果 你 想 进 行 更 多 的 实验 ， 你 可 以 用 不 
同 的 参数 重复 执行 enqueue() 调用 。 队列 中 存储 的 有 关 任 务 的 数据 将 保留 一 段 时 间 (默认 为 
500 秒 ) ， 但 最 终 会 被 删除 。 这 很 重要 ， 任 务 队 列 不 保留 已 执行 作业 的 历史 记录 。 


报告 任务 进度 


上 面 使 用 的 示例 任务 简单 得 不 现实 。 通常 ， 对 于 长 时 间 运 行 的 任务 ， 你 需要 将 一 些 进度 信息 
提供 给 应 用 程序 ， 从 而 可 以 将 其 显示 给 用 户 。 RQ 通 过 使 用 作业 对 象 的 meta 属性 来 支持 这 一 
点 。 让 我 重 写 example() 任务 来 编写 进 井 度 报告 : 


app/tasks.py: : 带 进 度 的 示例 后 台 任 务 。 


import time 
from rq import get_current_job 


def example(seconds): 
job = get_current_job() 
print('Starting task') 
for i in range(seconds): 
job.meta['progress'] = 100.0 * i / seconds 
job.save_meta() 
print(i) 
time.sleep(1) 
job.meta['progress'] = 100 
job.save_meta() 
print('Task completed’ ) 


这 个 新 版 本 的 example() 使 用 RQ 的 get_current_job() 函数 来 获取 一 个 作业 实例 该 实例 与 
是 交 任 务 时 返回 给 应 用 程序 的 实例 类 似 。 作 业 对 象 的 meta 属性 是 一 个 字典 ， 任 务 可 以 编写 
任何 想 要 与 应 用 程序 通信 的 自 定义 数据 。 在 这 个 例子 中 ， 我 写 入 了 progress ， 表 示 完 成 任务 
的 百分比 。 每 次 进程 更 新 时 ， 我 都 调用 job.save_meta() 指示 RQ 将 数据 写 入 Redis， 应 用 程 
序 可 以 在 其 中 找到 它 


在 应 用 程序 方面 (目前 只 是 一 个 Python shell) ， 我 可 以 运行 此 任务 ， 然 后 监视 进度 ， 如 下 所 
T: 


>>> job = queue.enqueue('app.tasks.example', 23) 
>>> job.meta 


>>> job.refresh() 

>>> job.meta 

{'progress': 13.043478260869565} 
>>> job.refresh() 

>>> job.meta 

{'progress': 69.56521739130434} 
>>> job.refresh() 

>>> job.meta 

{'progress': 100} 

>>> job.is_finished 

True 


如 你 所 见 ， 在 另 一 侧 ， meta 属性 可 以 被 读 取 。 需要 调用 refresh() 方法 来 从 Redis 更 新 内 
容 


Br o 


务 的 数据 库 表示 


对 于 上 面 的 例子 来 说 ， 启 动 一 个 任务 并 观察 它 运 行 就 足够 了 。 对 于 Web 应 用 程序 ， 情 况 会 变 
得 更 复杂 一 些 ， 因 为 一 旦 任务 随 着 请 求 的 处 理 而 启动 ， 该 请 求 随即 结束 ， 而 该 任务 的 所 有 上 
下 文 都 将 丢失 。 因为 我 希望 应 用 程序 跟踪 每 个 用 户 正 在 运行 的 任务 ， 所 以 我 需要 使 用 数据 库 
表 来 维护 状态 。 你 可 以 在 下 面 看 到 新 的 task 模型 实现 


app/models.py : Task 模 型 。 


# wn, 
import redis 
import rq 


class User(UserMixin, db.Model): 
tasks = db.relationship('Task', backref='user', lazy='dynamic' ) 


# wn. 


class Task(db.Model): 
id = db.Column(db.String(36), primary_key=True) 
name = db.Column(db.String(128), index=True) 
description = db.Column(db.String(128) ) 
user_id = db.Column(db.Integer, db.ForeignkKey('user.id')) 
complete = db.Column(db.Boolean, default=False) 


def get_rq_job(self): 
try: 
rq_job = rq.job.Job.fetch(self.id, connection=current_app.redis) 
except (redis.exceptions.RedisError, rq.exceptions.NoSuchJobError): 
return None 
return rq_job 


def get_progress(self): 
job = self.get_rq_job() 
return job.meta.get('progress', ©) if job is not None else 100 


这 个 模型 和 以 前 的 模型 有 一 个 有 趣 的 区 别 是 id 主键 字段 是 字符 串 类 型 ， 而 不 是 整数 类 型 。 
这 是 因为 对 于 这 个 模型 ， 我 不 会 依赖 数据 库 自己 的 主键 生成 ， 而 是 使 用 oes 


该 模型 将 存储 符合 任务 命名 规范 的 名 称 (会 传递 给 RQ) ， 适 用 于 向 用 户 显示 的 任务 描述 ， 该 
任务 的 所 属 用 户 的 关 系 以 及 任务 是 否 已 完成 的 布尔 值 ° complete 字段 的 目 的 是 将 正在 运 和 于 的 
任务 与 已 完成 的 任务 分 开 ， 因 为 运行 中 的 任务 需要 特殊 处 理 才 能 显示 最 新 进度 


get_rq_job() 辅助 方法 可 以 用 给 定 的 任务 ID 加 载 RQ Job 实例 。 这 是 通过 Job.fetch() 完成 

的 ， 它 会 从 Redis 中 存在 的 数据 中 加 载 Joo 实例 。 ee 方法 建立 

在 get_rq_job() 的 基础 之 上 ， 并 返回 任务 的 进度 百分比 。 该 方法 做 一 些 有 趣 的 假设 ， 如 果 模 
型 中 的 作业 ID 不 存在 于 RQ 队 列 中 ， 则 表示 作业 oo 期 并 已 从 队列 中 删除 ， 因 
此 在 这 种 情况 下 返回 的 百分比 为 100。 另 一 a a ae ， 但 'meta' 属 性 中 找 不 到 进度 相 
关 的 信息 ， 那 么 可 以 安全 地 假定 该 job 计划 运 但 还 没有 启动 ， 所 以 在 这 种 情况 下 进度 是 0。 


要 将 更 改 应 用 于 数据 库 ， 需 要 生成 新 的 迁移 ， 然 后 升级 数据 库 : 


(venv) $ flask db migrate -m "tasks" 
(venv) $ flask db upgrade 


新 模型 也 可 以 添加 到 shell 上 下 文中 ， 以 便 在 shell 会 话 中 访问 它 时 无 需 导 入 : 


microblog.py : 添加 Task 模 型 到 shell 上 下 文中 。 


from app import create_app, db, cli 
from app.models import User, Post, Message, Notification, Task 


app = create_app() 
cli.register (app) 


@app.shell_context_processor 
def make_shell_context(): 


return {'db': db, 'User': User, 'Post': Post, 'Message': Message, 
"Notification': Notification, 'Task': Task} 


将 RQ 与 Flask 应 用 集成 
Redis 服 务 的 连接 URL 需 要 添加 到 配置 中 : 


class Config(object): 
# a 


REDIS_URL = os.environ.get('REDIS URL') or 'redis://' 


与 往常 一 样 ，Redis 连 接 URL 将 来 自 环境 变量 ， 如 果 该 变量 未 定义 ， 则 会 假定 该 服务 在 当前 主 
机 的 默认 端口 上 运行 并 使 用 默认 URL © 


应 用 工厂 函数 将 负责 初始 化 Redis 和 RQ : 
app/init.py : 整合 RQ ° 


# ,,， 

from redis import Redis 
import rq 

# ,,， 


def create_app(config_class=Config): 
# 


app.redis = Redis.from_url(app.config['REDIS_URL']) 
app.task_queue = rq.Queue('microblog-tasks', connection=app.redis) 


# ... 


app.task_queue 将 成 为 提交 任务 的 队列 。 将 队列 附加 到 应 用 上 会 提供 很 大 的 便利 ， 因 为 我 可 
以 在 应 用 的 任何 地 方 使 用 current_app.task_queue 来 访问 它 。 为 了 方便 应 用 的 任何 部 分 提交 
或 检查 任务 ， 我 可 以 在 user 模型 中 创建 一 些 辅助 方法 : 


app/models.py : 用 户 模 型 中 的 任务 辅助 方法 。 


# ... 


class User(UserMixin, db.Model): 
# on. 


def launch_task(self, name, description, *args, **kwargs): 
rq_job = current_app.task_queue.enqueue('app.tasks.' + name, self.id, 
*args, **kwargs) 
task = Task(id=rq_job.get_id(), name=name, description=description, 
user=self) 
db.session.add(task) 
return task 


def get_tasks_in_progress(self): 
return Task.query.filter_by(user=self, complete=False).all() 


def get_task_in_progress(self, name): 
return Task.query.filter_by(name=name, user=self, 
complete=False).first() 


launch_task() 方法 负责 将 任务 提交 到 RQ 队 列 ， 并 将 其 添加 到 数据 库 中 。 name 参数 是 函数 
名 称 ， 如 app/tasks.py 中 所 定义 的 那样 。 提 交 给 RQ 时 ， 该 函数 会 将 app.tasks. 预先 添加 到 该 
名 称 中 以 构建 符合 规范 的 函数 名 称 。 description 参数 是 对 呈现 给 用 户 的 任务 的 友好 描述 。 
对 于 导出 用 户 动态 的 函数 ， 我 将 名 称 设置 为 export_posts ， 将 描述 设置 

为 Exporting posts... ° 其 余 参 数 将 传递 给 任务 函数 ° launch_task() HA AW i 队列 

的 enqueue() 方法 来 提交 作业 。 返回 的 作业 对 得 包含 由 RQ 分 配 的 任务 IDD， 因 此 我 可 以 使 用 它 
在 我 的 数据 库 中 创建 相应 的 Task 对 象 。 


请 注意 ， launch_task() 将 新 的 任务 对 象 添加 到 会 话 中 ， 但 不 会 发 出 提交 。 一 般 来 说 ， 最 好 
在 更 高 层次 函数 中 的 数据 库 会 话 上 进行 操作 ， 因 为 它 允 许 你 在 单个 事务 中 组 合 由 较 低 级 别 函 
数 所 做 的 多 个 更 新 。 这 不 是 一 个 严格 的 规则 ， 并 且 ， 在 本 章 后 面 的 子 函 数 中 也 会 存在 一 个 例 
外 的 提交 。 


get_tasks_in_progress() 方法 返回 该 用 户 未 完成 任务 的 列表 。 稍 后 你 会 看 到 ， 我 使 用 此 方法 
在 将 有 关 正 在 运行 的 任务 的 信息 泻 染 到 用 户 的 页 面 中 。 


最 后 ” get_task_in_progress() 是 上 一 个 方法 的 简化 版 本 并 返回 指定 的 任务 我 阻止 用 户 同 
时 启动 两 个 或 多 个 相同 类 型 的 任务 ， 因 此 在 启动 任务 之 前 ， 可 以 使 用 此 方法 来 确定 前 一 个 任 
务 是 否 还 在 运行 。 


利用 RQ 任务 发 送 电 子 邮件 


不 要 认为 本 节 偏 离 主 题 ， 我 在 上 面 说 过 ， 当 后 人 台 导 出 任务 完成 时 ， 将 使 用 包含 所 有 用 户 动态 

的 JSON 文 件 向 用 户 发 送 电子 邮件 。 我 在 第 十 章 中 构建 的 电子 邮件 功能 需要 通过 两 种 方式 进 

行 扩展 。 首先 ， 我 需要 添加 对 文件 附件 的 支持 ， 以 便 我 可 以 附加 JSON 文 件 。 其 

次 ， send_email() 函数 总 是 使 用 后 台 线 程 异 步 发 送 电子 邮件 。 当 我 要 从 后 台 任 务 发 送 一 封 电 
子 邮 件 时 〈 已 经 是 异步 的 了 ) ， 基 于 线程 的 二 级 后 台 任 务 没 有 什么 意义 ， 所 以 我 需要 同时 支 

持 同步 和 异步 电子 邮件 的 发 送 。 


幸运 的 是 ，Flask-Mail 支 持 附 件 ， 所 以 我 需要 做 的 就 是 扩展 send_email() 函数 的 默认 关键 字 参 
数 ， 然 后 在 message 对 象 中 配置 它们 。 选择 在 前 台 发 送 电子 邮件 时 ， 我 只 需要 添加 一 
个 sync=True 的 关键 字 参 数 即 可 : 


app/email.py : 发 送 带 附件 的 邮件 。 


# ... 


def send_email(subject, sender, recipients, text_body, html_body, 
attachments=None, sync=False): 
msg = Message(subject, sender=sender, recipients=recipients) 
msg.body = text_body 
msg.html = html_body 
if attachments: 
for attachment in attachments: 
msg.attach(*attachment ) 
if sync: 
mail.send(msg) 
else: 
Thread(target=send_async_email, 
args=(current_app._get_current_object(), msg)).start() 


Message 49 attach() 方法 接受 三 个 定义 附件 的 参数 : 文件 名 ， 媒 体 类 型 和 实际 文件 数据 。 
文件 名 就 是 收 件 人 看 到 的 与 附件 关联 的 名 称 。 媒体 类 型 定义 了 这 种 附件 的 类 型 ， 这 有 助 于 电 
子 邮件 读者 适当 地 演 染 它 。 例 如 ， 如 果 你 发 送 image/png 作为 媒体 类 型 ， 则 电子 邮件 阅读 器 
会 知道 该 附件 是 一 个 图 像 ， 在 这 种 情况 下 ， 它 可 以 显示 它 。 对 于 用 户 动态 数据 文件 ， 我 将 使 
用 JSON 格 式 3 该 格式 使 用 application/json 媒体 类 型 7 最 后 一 个 参数 包含 附件 内 容 的 字符 
PAPAA 


简单 来 说 ， send_email() 的 attachments 参数 将 成 为 一 个 元 组 列表 ， 每 个 元 组 将 有 三 个 元 素 
对 应 于 attach() 的 三 个 参数 。 因此 ， 我 需要 将 此 列表 中 的 每 个 元 素 作 为 参数 发 送 

给 attach() ° 在 Python 中 ， 如 果 你 想 将 列表 或 元 组 中 的 每 个 元 素 作 为 参数 传递 给 函数 ， 你 可 
以 使 用 func(*args) 将 这 个 列表 或 元 祖 解 包 成 函数 中 的 多 个 参数 ， 而 不 必 枯燥 地 一 个 个 地 传 
递 ， 如 func(args[0], args[1], args[2]) ° 例如 ， 如 果 你 有 一 个 列 

表 args = [1, 'foo'] ， func(*args) 将 会 传递 两 个 参数 ， 就 和 你 调用 func(1, 'foo') 一 样 。 
如 果 没 有 * ， 调 用 将 会 传 入 一 个 参数 ， 即 args WR 


至 于 电子 邮件 的 同步 发 送 ， 我 需要 做 的 就 是 ， 当 sync 是 True 的 时 候 恢复 成 调 
用 mail.send(msg) ° 


任务 助手 


尽管 我 上 面 使 用 的 example() 任务 是 一 个 简单 的 独立 函数 ， 但 导出 用 户 动 态 的 函数 却 需要 应 
用 中 具有 的 一 些 功 能 ， 例 如 访问 数据 库 和 发 送 电 子 邮件 。 因 为 这 将 在 单独 的 进程 中 运行 ， 所 
以 我 需要 初始 化 Flask-SQLAIchemy 和 Flask-Mail， 而 Flask-Mail 又 需要 Flask 应 用 实例 以 从 中 
获取 它们 的 配置 。 因 此 ， 我 将 在 app/tasks.py 模 块 的 顶部 添加 Flask 应 用 实例 和 应 用 上 下 文 : 


app/tasks.py : 创建 应 用 及 其 上 下 文 。 


from app import create_app 


app = create_app() 
app.app_context().push() 


应 用 在 此 模块 中 创建 ， 因 为 这 是 RQ worker 要 导入 的 唯一 模块 。 当 使 用 flask 命令 时 ， 根 目 
录 中 的 microblog.py 模 块 创建 应 用 实例 ， 但 RQ worker 对 此 却 一 无 所 知 ， 所 以 当 任 务 函数 需要 
它 时 ， 它 需要 创建 自己 的 应 用 实例 。 你 已 经 在 好 几 个 地 方 看 到 T ARET i 
送 一 个 上 下 文 使 应 用 成 为 “当前 "的 应 用 实例 ， 这 样 一 来 Flask-SQLAIchemy 等 插件 才 可 以 使 
用 current_app.config 获取 它们 的 配置 。 没 有 上 下 文 ， current app 表达 式 会 返回 一 个 错 


`a 
IR ° 


后 我 开始 考虑 如 何在 这 个 函数 运行 时 报告 进度 。 除 了 通过 job.meta 字典 传递 进度 信息 之 
外 ， 我 还 想 将 通知 推送 给 客户 端 ， 以便 自动 动态 更 新 完成 百分比 。 为 此 ， 我 将 使 用 我 在 第 
十 一 章 中 构建 的 通知 机 制 。 更 新 将 以 与 未 读 消息 徽章 非常 类 似 的 方式 工作 。 当 服务 器 浑 染 模 
板 时 ， 它 将 包含 从 job.meta 获得 的 “静态 "进度 信息 ， 但 是 一 旦 页 面 位 于 客户 端 | ERP? 
通知 将 使 用 通知 来 动态 更 新 百分比 。 由 于 通知 的 原因 ， 更 新 正在 运行 的 任务 的 进度 将 比 上 一 
个 示例 中 的 操作 稍微 多 一 些 ， 所 以 我 将 创建 一 个 专用 于 更 新 进度 的 包装 函数 : 


app/tasks.py : 设置 任务 进度 


from rq import get_current_job 
from app import db 
from app.models import Task 


# ... 


def _set_task_progress(progress): 
job = get_current_job() 
if job: 
job.meta['progress'] = progress 
job.save_meta() 
task = Task.query.get(job.get_id()) 
task.user.add_notification('task_progress', {'task_id': job.get_id(), 
"progress': progress}) 
if progress >= 100: 
task.complete = True 
db.session.commit() 


导出 任务 可 以 调用 _set_task_progress() 来 记录 进度 百分比 。 该 函数 首先 将 百分比 

入 job.meta 字典 并 将 其 保存 到 Redis， 然 后 从 数据 库 加 载 相 应 的 任务 对 象 ， 并 使 

用 task.user 已 有 的 add_notification() 方法 将 通知 推送 给 请 求 该 任务 的 用 户 P 通知 将 被 命 
名 为 task _progress ， mera snp 目的 字典 : 任务 标识 符 和 进度 数 
值 。 稍 后 我 将 添加 JavaScript 代 码 来 处 理 这 种 新 的 通知 类 型 。 


该 函数 查看 进度 来 确认 任务 函数 是 否 已 完成 ， 并 在 这 种 情况 下 更 新 数据 库 中 任务 对 象 

的 complete 属性 。 数据库 提交 调用 确保 通过 add_notification() 添加 的 任务 和 通知 对 象 都 立 
即 保存 到 数据 库 。 我 需要 非常 精确 地 设计 父 任务 ， 确 保 不 执行 任何 数据 库 更 改 ， 因 为 执行 本 
调用 会 将 父 任 务 的 更 改 也 写 入 数据 库 。 


实现 导出 任务 
现在 所 有 的 准备 工作 已 经 完成 ， 可 以 开始 编写 导出 函数 了 。 这 个 函数 的 高 层 结构 如 下 : 


app/tasks.py : 导出 用 户 动态 通用 结构 。 


def export_posts(user_id): 
try: 
# read user posts from database 
# send email with data to user 
except: 
# handle unexpected errors 


为 什么 将 整个 任务 包装 在 try/except 块 中 呢 ? 请 ee 中 的 应 用 代码 可 以 防止 意外 错误 ， 因 
为 Flask 本 身 捕 获 异 常 ， 然 后 将 它们 以 我 设置 的 日 志 配 置 的 方式 来 进行 处 理 。 然而 ， 这 个 函数 
将 运行 在 由 RQ 控 制 的 单独 进程 中 ， 而 非 Flask ， ， 任务 将 中 止 ， 
RQ 将 向 控制 台 显 示 错 误 ， 然 后 返回 等 待 新 的 job 。 所 以 基本 上 ， 除 非 你 正在 观看 RQ worker 的 
输出 或 将 其 记录 到 文件 中 ， 否 则 将 永远 不 会 发 现 有 错误 。 


让 我 们 从 上 面 带 有 注释 的 三 部 分 中 最 简单 的 错误 处 理 部 分 开始 杭 理 
app/tasks.py : 导出 用 户 动态 错误 处 理 。 

import sys 

# a 


def export_posts(user_id): 
try: 
# ... 
except: 
_set_task_progress(100) 
app. logger.error('Unhandled exception', exc_info=sys.exc_info()) 


每 当 发 生意 外 错误 时 ， 我 将 通过 将 进度 设置 为 100% 来 将 任务 标记 为 完成 ， 然 后 使 用 Flask 应 
用 程序 中 的 日 志 记 录 器 对 象 记录 错误 以 及 堆栈 跟踪 信息 (调用 sys.exc_info() 来 获得 ) ° 使 
用 Flask 应 用 日 志 记 录 器 来 记录 错误 的 好 处 在 于 ， 你 可 以 观察 到 你 为 Flask 应 用 实现 的 任何 日 志 
记录 机 制 。 例 如 ， 在 第 七 草 中 ， 我 配置 了 要 发 送 到 管理 员 电 子 邮 件 地 址 的 错误 。 只 要 使 

用 app.logger ， 我 也 可 以 得 到 这 些 错误 信息 。 


接 下 来 ， 我 将 编写 实际 的 导出 代码 ， 它 只 需 发 出 一 个 数据 库 查询 并 在 循环 中 遍历 结果 ， 并 将 
它们 累积 在 字典 中 : 


app/tasks.py : 从 数据 库 读 取 用 户 动态 。 


import time 
from app.models import User, Post 


# i... 


def export_posts(user_id): 
try: 

user = User.query.get(user_id) 

_set_task_progress(0) 

data = [] 

i=0 

total_posts = user.posts.count() 

for post in user.posts.order_by(Post.timestamp.asc()): 
data.append({'body': post.body, 

"timestamp': post.timestamp.isoformat() + 'Z'}) 

time.sleep(5) 
i += 1 
_set_task_progress(100 * i // total_posts) 


# send email with data to user 


except: 
# ... 


每 条 动态 都 是 一 个 包含 两 个 条 目的 字典 ， 即 动态 正文 和 动态 发 表 的 时 间 。 时 间 格 式 将 采 
用 ISO 8601 标 准 。 我 使 用 的 Python 的 datetime 对 象 不 存储 时 区 ， 因 此 在 以 ISO 格式 导出 时 间 
后 ， 我 添加 了 'Z'， 它 表示 UTC ° 


由 于 需要 跟踪 进度 ， 代 码 变 得 稍微 复杂 了 些 。 我 维护 了 一 个 计数 器 i ， 并 且 在 进入 循环 之 前 
还 需要 发 出 一 个 额外 的 数据 库 查询 ， 查 询 total posts 以 获得 用 户 动 态 的 总 数 。 使 用 
[if total_posts ， 在 每 个 循环 迭代 我 都 可 以 使 用 从 0 到 100 的 数字 来 更 新 任务 进度 有 


你 可 能 会 好 奇 我 为 什么 会 在 每 个 循环 选 代 中 加 入 time.sleep(5) 调用 。 主要 原因 是 我 想 要 延长 
导出 所 需 的 时 间 ， 以 便 在 用 户 动态 不 多 的 情况 下 也 可 以 方便 地 查看 到 导出 进度 的 增长 。 


下 面 是 函数 的 最 后 部 分 ， 将 会 带 上 data 附件 发 送 邮件 给 用 户 : 


app/tasks.py : 发 送 带 用 户 动 态 的 邮件 给 用 户 。 


import json 

from flask import render_template 
from app.email import send_email 
# ,,， 


def export_posts(user_id): 


try: 
# .,， 
send_email('[Microblog] Your blog posts', 
sender=app.config['ADMINS'][0], recipients=[user.email], 
text_body=render_template('email/export_posts.txt', user=user), 
html_body=render_template('email/export_posts.html', user=user), 
attachments=[('posts.json', 'application/json', 
json.dumps({'posts': data}, indent=4))], 
sync=True) 
except: 


# ... 


其 实 只 是 对 send_email() 函数 的 调用 。 附件 被 定义 为 一 个 元 组 ， 其 中 有 三 个 元 素 被 传递 给 
Flask-Mail 的 message 对 象 的 attach() 方法 。 元 组 中 的 第 三 个 元 素 是 附件 内 容 ， 它 是 用 
Python 的 json.dumps() 函数 生成 的 。 


这 里 引用 了 一 对 新 模板 ， 它 们 以 纯 文本 和 HTML 格 式 提供 电子 邮件 正文 的 内 容 。 这 是 文本 模 
板 的 内 容 : 


app/templates/email/export_posts.txt : 导出 用 户 动态 文本 邮件 模板 。 


Dear {{ user.username }}, 
Please find attached the archive of your posts that you requested. 
Sincerely, 


The Microblog Team 


这 是 HTML 版 本 的 邮件 模板 : 


app/templates/email/export_posts.html : 导出 用 户 动态 HTML 邮 件 模板 。 


<p>Dear {{ user.username }},</p> 

<p>Please find attached the archive of your posts that you requested.</p> 
<p>Sincerely, </p> 

<p>The Microblog Team</p> 


应 用 中 的 导出 功能 


所 有 支持 后 台 导 出 任务 的 核心 组 件 现 已 到 位 。 剩 下 的 就 是 将 这 个 功能 连接 到 应 用 ， 以 便 用 户 
发 起 请 求 并 通过 电子 邮件 发 送 用 户 动态 给 他 们 。 


下 面 是 新 的 export_posts 视图 函数 : 


app/main/routes.py : 导出 用 户 动态 路 由 和 视图 函数 。 


@bp.route('/export_posts') 
@login_required 
def export_posts(): 
if current_user.get_task_in_progress('export_posts'): 
flash(_('An export task is currently in progress')) 
else: 
current_user.launch_task('export_posts', _('Exporting posts...')) 
db.session.commit() 
return redirect(url_for('main.user', username=current_user.username) ) 


该 函数 首先 检查 用 户 是 否 有 未 完成 的 导出 任务 ， 并 在 这 种 情况 下 只 是 闪现 消息 。 对 同一 用 户 
同时 执行 两 个 导出 任务 是 没有 意义 的 ， 可 以 避免 。 我 可 以 使 用 前 面 实现 
的 get_task_in_progress() 方法 来 检查 这 种 情况 。 


如 果 用 户 没有 正在 运行 的 导出 任务 ， 则 调用 launch_task() 来 启动 它 。 第 一 个 参数 是 将 传递 
给 RQ worker 的 函数 的 名 称 ， 前 级 为 app.tasks.。 第 二 个 参数 只 是 一 个 友好 的 文本 描述 ， 将 
会 显示 给 用 户 。 这 两 个 值 都 会 被 写 入 数据 库 中 的 Task 对 象 。 该 函数 以 重 定向 到 用 户 个 人 主页 
结束 。 


现在 我 需要 暴露 该 路 由 的 链接 ， 以 便 用 户 可 以 请 求 导 出 。 我 认为 最 合适 的 地 方 是 在 用 户 个 人 
主页 ， 只 有 在 用 户 查 看 他 们 自己 的 主页 时 ， 链 接 在 "编辑 个 人 资料 "链接 下 面 显 示 : 


app/templates/user.html : 用 户 个 人 主页 的 导出 链接 。 


<p> 
<a href="{{ url_for('main.edit_profile') }}"> 
{{ _('Edit your profile') }} 
</a> 
</p> 
{% if not current_user.get_task_in_progress('export_posts') %} 
<p> 
<a href="{{ url_for('main.export_posts') }}"> 
{{ _('Export your posts') }} 
</a> 
</p> 


{% endif %} 


此 链接 的 泻 梁 是 有 条 件 的 ， 因 为 我 不 希望 它 在 用 户 已 经 有 导出 任务 执行 时 出 现 。 


此 时 的 后 台 作 业 是 可 以 运作 的 ， 但 是 不 会 向 用 户 提 供 任 何 反 馈 。 如 果 你 想 尝试 一 下 ， 你 可 以 
按 如 下 方式 启动 应 用 和 RQ worker : 


。 确保 Redis 正 在 运行 

。 打开 一 个 终端 窗口 ， 启 动 至 少 一 个 RQ worker 实 例 。 本 处 你 可 以 运行 命 
令 rq worker microblog-tasks 

© 再 打开 另 一 个 终端 窗口 ， 使 用 flask run (记得 先 设置 Faska 变量 ) 命 令 启 动 Flask 应 
用 


进度 通知 


为 了 完善 这 个 功能 ， 我 想 在 后 台 任 务 运行 时 提醒 用 户 任 务 完 成 的 百分比 进度 。 在 浏览 
Bootstrap 组 件 选项 时 ， 我 决定 在 导航 栏 的 下 方 使 用 一 个 Alert 组 件 。 Alert 组 件 是 向 用 户 显示 信 
息 的 带 顾 色 的 横 条 。 我 用 蓝 色 的 Alert 框 来 泻 染 闪现 的 消息 。 现在 我 要 添加 一 个 绿色 的 Alert 杠 
来 显示 任务 进度 。 样式 如 下 : 


Microblog Home Explore Messages Profile Logout 


Exporting posts... 57% 


User: miguel 


Last seen on: November 23, 2017 2:35 PM 
0 followers, 0 following 


Edit your profile 





app/templates/base.html : 基础 模板 中 的 导出 进度 Alert 组 件 。 


{% block content %} 
<div class="container"> 
{% if current_user.is_authenticated %} 
{% with tasks = current_user.get_tasks_in_progress() %} 
{% if tasks %} 
{% for task in tasks %} 
<div class="alert alert-success" role="alert"> 
{{ task.description }} 
<span id="{{ task.id }}-progress">{{ task.get_progress() }}</span>% 
</div> 
{% endfor %} 
{% endif %} 
{% endwith %} 
{% endif %} 


{% endblock %} 


泻 染 任务 Alert 组 件 的 方法 几乎 与 闪现 消息 相同 。 外 部 条 件 在 用 户 未 登录 时 跳 过 所 有 与 Alert 相 
关 的 标记 。 而 对 于 已 登录 用 户 我 通过 调用 前 面 创 建 的 get_tasks_in_progress() 方法 来 获取 
当前 正在 进行 的 任务 列表 。 在 当前 版 本 的 应 用 中 ， 我 最 多 只 能 得 到 一 个 结果 ， 因 为 我 不 允许 
多 个 导出 任务 同时 执行 ， 但 将 来 我 可 能 要 支持 可 以 共存 的 其 他 类 型 的 任务 ， 所 以 以 通用 的 方 
式 泻 染 Alert 可 以 节省 我 以 后 的 时 间 。 


对 于 每 项 任务 ， 我 都 会 在 页 面 上 泻 染 一 个 Alert 元 素 。 Alert 的 颜色 由 第 二 个 CSS 样 式 控制 ， 本 
处 是 alert-success ， 而 在 闪现 消息 是 alert-info 。 Bootstrap 文 档 包 含有 关 Alert 的 HTML 结 
构 的 详细 信息 。Alert 文 本 包括 存储 在 Task 模型 中 的 description 字段 ， 后 面 跟着 完成 百 分 
比 。 


百分比 被 封装 在 具有 id 属性 的 <span> 元 素 中 。 原因 是 我 要 在 收 到 通知 时 用 JavaScript 刷 新 
百分比 。 我 给 任务 ID 末尾 附加 -progress 来 构造 id 属性 。 当 有 通知 到 达 时 ， 通 过 其 中 的 任 
务 ID， 我 可 以 很 容易 地 使 用 #<task.id>-progress 选择 器 找到 正确 的 <span> 元 素来 更 新 。 


如 果 你 此 时 进行 尝试 ， 则 每 次 导航 到 新 页 面 时 都 会 看 到 “静态 ”的 进度 更 新 。 你 可 以 注意 到 ， 
在 启动 导出 任务 后 ， 你 可 以 自由 导航 到 应 用 程序 的 不 同 页 面 ， 正 在 运行 的 任务 的 状态 始终 都 
会 展示 出 来 。 


为 了 对 span> 元 素 的 百分比 的 动态 更 新 做 准备 ， 我 将 在 JavaScript 端 编写 一 个 辅助 函数 : 


app/templates/base.html : 动态 更 新 任务 进度 的 辅助 函数 。 


{% block scripts %} 
<script> 
function set_task_progress(task_id, progress) { 
$('#' + task_id + '-progress').text(progress); 
</script> 


{% endblock %} 


这 个 函数 接受 一 个 任务 id 和 一 个 进度 值 ， ， 并 使 用 jQuery 为 这 个 任务 定位 <span> 元 素 ， 并 将 
新 进度 作为 其 内 容 写 入 。 实际 上 不 需要 验证 页 面 上 是 否 存在 该 元 素 ， 因 为 如 果 没 有 找到 该 元 
素 ，jQuery 将 不 会 执行 任何 操作 。 


app/tasks.py 中 的 _set_task_progress() 函数 每 次 更 新 进度 时 调用 add _notification() ， 就 会 
产生 新 的 通知 。 而 我 在 第 二 十 一 章 明 智 地 以 完全 通用 的 方式 实现 了 通知 功能 。 所 以 当 浏 览 器 
定期 向 服务 器 发 送 通知 更 新 请 求 时 ， 浏 览 器 会 获得 通过 add_notification() 方法 添加 的 任何 
通知 。 


f ， 这些 JavaScript 代 码 只 能 识别 人 有 unread_message_count 名 称 的 那些 通知 ， 并 忽略 其 
。 我 现在 需要 做 的 是 扩展 该 函数 ， 通 过 调用 我 上 面 定义 的 set_task_progress() i 
理 task_progress 通知 。 以 下 是 处 理 通知 更 新 版 本 JavaScript 代 码 : 


app/templates/base.html : 通知 处 理 器 。 


for (var i = 0; i < notifications.length; i++) { 
switch (notifications[i].name) { 
case 'unread_message_count': 
set_message_count(notifications[i].data); 
break; 
case 'task_progress': 
set_task_progress( 
notifications[i].data.task_id, 
notifications[i].data.progress); 
break; 


since = notifications[i].timestamp; 


现在 我 需要 处 理 两 个 不 同 的 通知 ， 我 决定 用 一 个 switch 18 4) FARE 

查 unread_message_count 通知 名 称 的 if 14) > His a 包含 我 现在 需要 支持 的 每 个 通知 ° 如 
果 你 对 “C” 系 列 语言 不 熟悉 ， 就 可 能 从 未 见 过 switch 语 句 ， 它 提供 了 一 种 方便 的 语法 ， 可 以 替 
代 一 长 囊 的 if/elseif 语句 。 这 是 一 个 很 棒 的 特性 ， 因 为 当 我 需要 支持 更 多 通知 时 ， 只 需 简 
单 地 添加 case 块 即 可 。 


回顾 一 下 ，RQ 任 务 附加 到 task_progress 通知 的 数据 是 一 个 包含 两 个 元 
素 task_id 和 progress 的 字典 ， 这 两 个 元 素 是 我 用 来 调用 set_task_progress() 的 两 个 参 
数 。 


如 果 你 现在 运行 该 应 用 ， 则 绿色 Alert 框 中 的 进度 指示 器 将 每 10 秒 刷新 一 次 〈 因 为 刷新 通知 的 
时 间 间 隔 是 10 秒 ) 。 

由 于 本 章 介绍 了 新 的 可 翻译 字符 串 ， 因 此 需要 更 新 翻译 文件 。 如 果 你 要 维护 非 英 语 语言 文 
件 ， 则 需要 使 用 Flask-Babel 刷 新 翻译 文件 ， 然 后 添加 新 的 翻译 : 


(venv) $ flask translate update 
如 果 你 使 用 的 是 西班牙 语 翻译 ， 那 么 我 已 经 为 你 完成 了 翻译 工作 ， 因 此 可 以 从 下 载 包 中 提取 
app/translations/es/LC_MESSAGES/messages.po 文 件 ， 并 将 其 添加 到 你 的 项 目 中 。 


翻译 文件 到 位 后 ， 还 要 编译 翻译 文件 : 


(venv) $ flask translate compile 


部 着 注意 事项 


为 了 完成 本 章 ， 我 还 要 讨论 应 用 程序 部 署 的 变化 。 为 了 支持 后 台 任 务 ， 我 在 部 署 栈 中 增加 了 
两 个 新 组 件 ， 一 个 Redis 服 务 器 和 一 /多 个 RQ worker。 很 明显 ， 它 们 需要 包含 在 部 署 策略 中 ， 
因此 我 将 简要 介绍 前 几 章 中 不 同 部 署 方式 的 一 些 调整 。 


部 署 到 Linux 服 务 器 
如 果 你 正在 Linux 服 务 器 上 运行 应 用 ， 则 添加 Redis 十 分 简单 。 对 于 Ubuntu Linux， 你 可 以 运 
行 sudo apt-get install redis-server 来 安装 Redis 服 务 器 。 


要 运行 RQ worker 进 程 ， 可 以 按照 第 十 七 章 中 “设置 Gunicorn 和 Supervisor” 一 节 那 样 创建 第 二 
个 Supervisor 配 置 ， 在 其 中 运行 的 命令 改 成 rq worker microblog-tasks ° 如 果 你 想 要 运行 多 
个 worker (假设 是 生产 环境 ) ， 则 可 以 使 用 Supervisor 的 numprocs 指令 来 指示 要 同时 运行 多 
少 个 实例 。 


部 署 到 Heroku 


要 在 Heroku 上 部 署 应 用 ， 你 需要 将 Redis 服 务 添加 到 你 的 帐户 。 这 与 我 添加 Postgres 数 据 库 
的 过 程 类 似 。Redis 也 有 一 个 免费 档次 ， 可 以 使 用 以 下 命令 添加 : 


$ heroku addons:create heroku-redis:hobby-dev 


新 的 redis 服 务 的 访问 URL 将 作为 REDIS_URL 变量 添加 到 你 的 Heroku 环 境 中 ， 这 正 是 应 用 所 需 
的 。 


Heroku 的 免费 方案 允许 同时 启动 一 个 web 进 程 和 一 个 worker 进 程 ， 因 此 你 可 以 在 免费 的 情况 
下 启动 一 个 rq Worker 进 程 。 为 此 ， 你 将 需要 在 procfile 的 一 个 单独 的 行 中 声明 worker : 


web: flask db upgrade; flask translate compile; gunicorn microblog:app 
worker: rq worker microblog-tasks 


将 这 些 变更 重新 部 署 之 后 ， 可 以 使 用 以 下 命令 启动 Worker : 


$ heroku ps:scale worker=1 


38 # 2] Docker 


如 果 你 将 应 用 程序 部 署 到 Docker 容 器 ， 那 么 首先 需要 创建 一 个 Redis 容 器 。 为 此 ， 你 可 以 使 
用 Docker 镜 像 仓库 中 的 其 中 一 个 官方 Redis 镜 像 : 


$ docker run --name redis -d -p 6379:6379 redis:3-alpine 


当 运 行 你 的 应 用 时 ， 你 需要 以 类 似 于 MySQL 容 器 的 链接 方式 ， 链 接 redis 容 器 并 设 
置 REDIS URL 环境 变量 。 下 面 是 一 个 完整 的 命令 来 启动 应 用 ， 包 含 了 一 个 redis 链 接 : 


$ docker run --name microblog -d -p 8000:5000 --rm -e SECRET_KEY=my-secret-key \ 
-e MAIL_SERVER=smtp.googlemail.com -e MAIL_PORT=587 -e MAIL_USE_TLS=true \ 
-e MAIL_USERNAME=<your -gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
--link mysql:dbserver --link redis:redis-server \ 
-e DATABASE_URL=mysql+pymysql://microblog:<database-password>@dbserver/microblog \ 
-e REDIS_URL=redis://redis-server:6379/0 \ 
microblog:latest 


你 需要 为 RQ worker 运 行 一 /多 个 容器 。 由 于 worker 与 主 应 用 具有 相同 的 代码 ， 因 此 可 
与 应 用 相同 的 容器 镜像 ， 并 和 替 盖 启动 命令 ， 以 便 启 动 Worker 而 不 是 Web 应 用 。 以 下 是 
启动 Worker 的 docker run 命令 


$ docker run --name rq-worker -d --rm -e SECRET_KEY=my-secret-key \ 
-e MAIL_SERVER=smtp.googlemail.com -e MAIL_PORT=587 -e MAIL_USE_TLS=true \ 
-e MAIL_USERNAME=<your -gmail-username> -e MAIL_PASSWORD=<your-gmail-password> \ 
--link mysql:dbserver --link redis:redis-server \ 
-e DATABASE_URL=mysqlt+pymysql://microblog:<database-password>@dbserver/microblog \ 
-e REDIS_URL=redis://redis-server:6379/0 \ 
--entrypoint venv/bin/rq \ 
microblog:latest worker -u redis://redis-server:6379/0 microblog-tasks 


#2. & Dockert 1% 89 RUB BNO A RHR ? 因为 命令 需要 分 两 部 分 给 出 ° --entrypoint BR 
只 取得 可 执行 文件 的 名 称 ， 但 是 参数 (如 果 有 的 话 ) 需要 在 镜像 和 标签 之 后 ， 也 就 是 在 命令 
行 的 结尾 处 给 出 。 请 注意 rq 命令 需要 使 用 venv/bin/rq ， 以 便 在 没有 手动 激活 虚拟 环境 的 情 
况 下 ， 也 能 识别 虚拟 环境 并 正常 工作 。 


本 文 翻 译 自 The Flask Mega-Tutorial Part XXIII: Application Programming Interfaces (APIs) 


我 为 此 应 用 程序 构建 的 所 有 功能 都 只 适用 于 特定 类 型 的 客户 端 : Web 浏 览 器 。 但 其 他 类 型 的 
客户 端 呢 ? 例如 ， 如 果 我 想 构 建 Android 或 iDS APP ， A LAT RTM AAR 个 问题 。 
最 简单 的 解决 方案 是 构建 一 个 简单 的 APP， 仅 使 用 一 个 Web 视 图 组 件 并 用 Microblog 网 站 填充 
整个 屏幕 ， 但 相 比 在 设备 的 Web 浏 览 器 中 打开 网 站 ， 这 种 方案 几乎 没有 什么 卖点 。 一 个 更 好 
的 解决 方案 (尽管 更 费力 ) 将 是 构建 一 个 本 地 APP， 但 这 个 APP 如 何 与 仅 返 回 HTML 页 面 的 服 
务 器 交互 呢 ? 


这 就 是 应 用 程序 编程 接口 (API) 的 能 力 范 畴 了 。 API 是 一 组 HTTP 路 由 ， 被 设计 为 应 用 程序 
FAT, 点 。 与 定义 返回 HTML 以 供 Web 浏 览 器 使 用 的 路 由 和 视图 函数 不 同 ，API 允 许 客 
户 端 直接 使 用 应 用 程序 的 资源 ， 从 而 决定 如 何 通过 客户 端 完全 地 向 用 户 呈 现 信 息 。 例 如 ， 
Microblog 中 的 API 可 以 向 用 户 提供 用 户 信息 和 用 户 动 态 ， 并 且 它 还 可 以 允许 用 户 编辑 现 有 动 

态 ， 但 仅 限于 数据 级 别 ， 不 会 将 此 逻辑 与 HTML 混 合 。 


如 果 你 研究 了 应 用 程序 中 当前 定义 的 所 有 路 由 ， 会 注意 到 其 中 的 几 个 符合 我 上 面 使 用 的 API 的 
定义 。 找 到 它们 了 吗 ? 我 说 的 是 返回 JSON 的 几 条 路 由 ， 比 如 第 十 四 章 中 定义 的 /translate 路 
由 。 这 种 路 由 的 内 容 都 以 JSON 格 式 编码 ， 并 在 请 求 时 使 用 posT 方法 。 此 请 求 的 响应 也 是 
JSON 格 式 ， 服 务 器 仅 返 回 所 请 求 的 信息 ， 客 户 端 负责 将 此 信息 呈现 给 用 户 。 


虽然 应 用 程序 中 的 JSON 路 由 具有 API 的 “感觉 ”， 但 它们 的 设计 初衷 是 为 支持 在 浏览 器 中 运行 

的 Web 应 用 程序 。 设 想 一 下 ， 如 果 智能 手机 APP 想 要 使 用 这 些 路 由 ， 它 将 无 法 使 用 ， 因 为 这 
需要 用 户 登 录 ， 而 登录 只 能 通过 HTML 表 单 进行 。 在 本 章 中 ， 我 将 展示 如 何 构建 不 依赖 于 
Web 浏 览 器 的 API， 并 且 不 会 假设 连接 到 它们 的 客户 端的 类 型 。 


本 章 的 GitHub 链 接 为 : Browse, Zip, Diff. 
REST API 设 计 风 格 


RESTasaFoundation of API Design 


有 些 人 可 能 会 强烈 反对 上 面 提 到 的 [anslate 和 其 他 JSON 路 由 是 API 路 由 。 其 他 人 可 能 会 同 
意 ， 但 也 会 认为 它们 是 一 个 设计 糟糕 的 AP|。 那么 一 个 精心 设计 的 API 有 什么 特点 ， 为 什么 上 
面 的 JSON 路 由 不 是 一 个 好 的 API 路 由 呢 ? 


你 可 能 听 说 过 REST API。 REST (Representational State Transfer) 是 Roy Fielding 在 博士 
论文 中 提出 的 一 种 架构 。 该 架构 中 ，Dr Fielding 以 相当 抽象 和 通用 的 方式 展示 了 REST 的 六 
个 定义 特征 。 


余 了 DrFielding 的 论文 外 ， 没 有 关于 REST 的 权威 性 规范 ， 从 而 留 下 了 许多 细节 供 读 者 解读 。 
一 个 给 定 的 API 是 否 符合 REST 规 范 的 话题 往往 是 REST“ 纯 粹 主义 者 "之 间 激 烈 争 论 的 源头 ， 
REST" 纯 粹 主义 者 "认为 REST API 必 须 以 非常 明确 的 方式 遵循 全 部 六 个 特征 ， 而 不 像 REST" 实 


用 主义 者 那样， 仅仅 将 Dr. Fielding 在 论文 中 提出 的 想法 作为 指导 原则 或 建议 。DrFielding 站 
在 纯粹 主义 阵营 的 一 边 ， 并 在 博客 文章 和 在 线 评论 中 的 撰写 了 一 些 额 外 的 见解 来 表达 他 的 愿 


景 。 


目前 实施 的 绝 大 多 数 API 都 遵循 “实用 主义 "的 REST 实 现 。 包括 来 自 Facebook，GitHub ， 
Twitter 等 “大 玩家 "的 大 部 分 API 都 是 如 此 。 很 少 有 公共 API 被 一 致 认 为 是 纯 REST， 因 为 大 多 数 
API 都 没有 包含 纯粹 主义 者 认为 必须 实现 的 某 些 细节 。 尽管 Dr. Fielding 和 其 他 REST 纯 粹 主义 
者 对 评判 一 个 API 是 否 是 REST API 有 严格 的 规定 ， 但 软件 行业 在 实际 运用 中 引用 REST 是 很 常 
见 的 。 


为 了 让 你 了 解 REST 论 文中 的 内 容 ， 以 下 各 节 将 介绍 Dr. Fielding 列 举 的 六 项 原则 。 
客户 端 一 服务 器 
客户 端 一 服务 器 原则 相当 简单 ， 正 如 其 字面 含义 ， 在 REST API 中 ， 客 户 端 和 服务 器 的 角色 应 


该 明确 区 分 。 在 实践 中 ， 这 意味 着 客户 端 和 服务 器 都 是 单独 的 进程 ， 并 在 大 多 数 情况 下 ， 使 
用 基于 TCP 网 络 上 的 HTTP 协 议 进 行 通信 © 


的 服务 器 。 因此 ， 对 于 客户 端 来 说 ， 如 果 不 直接 连接 到 服务 器 ， 它 发 送 请 求 的 方式 应 该 没有 
什么 区 别 ， 事 实 上 ， 它 甚至 可 能 不 知道 它 是 否 连接 到 目标 服务 器 。 同样 ， 这 个 原则 规定 服务 
器 兼容 直接 接收 来 自 代 理 服 务 器 的 请 求 ， 所 以 它 绝 不 能 假设 连接 的 另 


分 层 系 统 原 则 是 说 当 客 户 端 需要 与 服务 器 通信 时 ， 它 可 能 最 终 连 接 到 代理 服务 器 而 不 是 实际 


一 端 一 定 是 客户 端 。 


这 是 REST 的 一 个 重要 特性 ， 因 为 能 够 添加 中 间 节 点 的 这 个 特性 ， 允 许 应 用 程序 架构 师 使 用 负 
载 均 和 衡器， 缓存， 代理 服务 器 等 来 设计 满足 大 量 请 求 的 大 型 复杂 网 络 。 


该 原则 扩展 了 分 层 系 统 ， 通 过 明确 指出 允许 服务 器 或 代理 服务 器 缓存 频繁 且 相同 请 求 的 响应 
内 容 以 提高 系统 性 能 。 有 一 个 你 可 能 熟悉 的 缓存 实现 : 所 有 Web 浏 览 器 中 的 缓存 。 Webà I 
器 缓存 层 通常 用 于 避免 一 遍 又 一 遍地 请 求 相同 的 文件 ， 例 如 图 像 。 


为 了 达到 API 的 目的 ， 目 标 服务 器 需要 通过 使 用 缓存 控制 来 指示 响应 是 否 可 以 在 代理 服务 器 传 
回 客户 端 时 进行 缓存 。 请 注意 ， 由 于 安全 原因 ， 部 署 到 生产 环境 的 API 必 须 使 用 加 密 ， 因 此 ， 
除非 此 代理 服务 器 terminates SSL 连 接 ， 或 者 执行 解密 和 重新 加 密 ， 和 否则 缓存 通常 不 会 在 代理 
服务 器 中 完成 。 


按 需 获取 客户 端 代码 (Code On Demand) 


这 是 一 项 可 选 要 求 ， 规 定 服务 器 可 以 提供 可 执行 代码 以 响应 窗户 端 ， 这 样 一 来 ， 就 可 以 从 服 
务 器 上 获取 客户 端的 新 功能 。 因为 这 个 原则 需要 服务 器 和 客户 端 之 间 就 客户 端 能 够 运行 的 可 

执行 代码 类 型 达成 一 致 ， 所 以 这 在 API 中 很 少 使 用 。 你 可 能 会 认为 服务 器 可 能 会 返回 
JavaScript 代 码 以 供 Web 浏 览 器 客户 端 执行 ， 但 REST 并 非 专 门 针 对 Web 浏 览 器 客户 端 而 设 
计 。 例 如 ， 如 果 客 户 端 是 iOS 或 Android 设 备 ， 执 行 JavaScript 可 能 会 带 来 一 些 复杂 情况 。 


无 状态 


无 状态 原则 是 REST 纯 粹 主义 者 和 实用 主义 者 之 间 争 论 最 多 的 两 个 中 心 之 一 。 它 指出 ，REST 
API 不 应 保存 客户 端 发 送 请 求 时 的 任何 状态 。 这 意味 着 ， 在 Web 开 发 中 常见 的 机 制 都 不 能 在 用 
户 浏览 应 用 程序 页 面 时 “ 记 住 ”用户 。 在 无 状态 APl 中 ， 每 个 请 求 都 需要 包含 服务 器 需要 识别 和 
验证 客户 端 并 执行 请 求 的 信息 。 这 也 意味 着 服务 器 无 法 在 数据 库 或 其 他 存储 形式 中 存储 与 客 
户 端 连接 有 关 的 任何 数据 。 


如 果 你 想 知道 为 什么 REST 需 要 无 状态 服务 器 ， 主 要 原因 是 无 状态 服务 器 非常 容易 扩展 ， 你 只 
需 在 负载 均衡 器 后 面 运行 多 个 服务 器 实例 即 可 。 如 果 服 务 器 存储 客户 端 状态 ， 则 事情 会 变 得 
更 复杂 ， 因 为 你 必须 弄 清 楚 多 个 服务 器 如 何 访 问 和 更 新 该 状态 ， 或 者 确保 给 定 客户 端 始终 由 
同一 服务 器 处 理 ， 这 样 的 机 制 通常 称 为 粘性 会 话 。 


再 思考 一 下 本 章 介 绍 中 讨论 的 [anslale 路 由 ， 就 会 发 现 它 不 能 被 视 为 RESTfuj ， 因 为 与 该 路 由 
相关 的 视图 函数 依赖 于 Flask-Login 的 @login_required 装饰 器 ， 这 会 将 用 户 的 登录 状态 存储 
在 Flask 用 户 会 话 中 。 


统一 接口 


最 后 ， 最 重要 的 ， 最 有 争议 的 ， 最 含糊 不 清 的 REST 原 则 是 统一 接口 。Dr Fielding 列 举 了 
REST 统 一 接口 的 四 个 特性 : 唯一 资源 标识 符 ， 资 源 表 示 ， 自 描述 性 消息 和 超 媒体 。 


唯一 资源 标识 符 是 通过 为 每 个 资源 | 。 例 如 ， 与 给 定 用 户 关 联 的 URL 
可 以 是 /apjusers/， 其 中 是 在 数据 库 表 主键 中 分 配给 用 户 的 标识 符 。 大 多 数 API 都 能 很 好 地 实 
现 这 一 点 。 


资源 表示 的 使 用 意味 着 当 服 务 器 和 客户 端 交 换 关 于 资源 的 信息 时 ， 他 们 必须 使 用 商定 的 格 
式 。 对 于 大 多 数 现 代 API，JSON 格 式 用 于 构建 资源 表示 。 API 可 以 选择 支持 多 种 资源 表示 格 
式 ， 并 且 在 这 种 情况 下 ，HTTP 协 议 中 的 内 容 协 商 选 项 是 客户 端 和 服务 器 确认 格式 的 机 制 。 


自 描述 性 消息 意味 着 在 客户 端 和 服务 器 之 间 交 换 的 请 求 和 响应 必须 包含 对 方 需要 的 所 有 信 

息 。 作为 一 个 典型 的 例子 ，HTTP 请 求 方法 用 于 指示 客户 端 希望 服务 器 执行 的 操作 。 GET 请 
求 表示 客户 想 要 检索 资源 信息 ， post 请 求 表示 客户 想 要 创建 新 资源 ， PUT 或 parch 请 求 定 
义 对 现 有 资源 的 修改 ， DELETE 表示 删除 资源 的 请 求 。 目标 资源 被 指定 为 请 求 的 URL， 并 在 
HTTP 头 ，URL 的 查询 字符 串 部 分 或 请 求 主体 中 提供 附加 信息 。 


超 媒体 需求 是 最 具 争 议 性 的 ， 而 且 很 少 有 API 实 现 ， 而 那些 实现 它 的 API 很 少 以 满足 REST 纯 粹 
主义 者 的 方式 进行 。 由 于 应 用 程序 中 的 资源 都 是 相互 关联 的 ， 因 此 此 要 求 会 要 求 将 这 些 关系 
包含 在 资源 表示 中 ， 以 便 客 户 端 可 以 通过 遍历 关系 来 发 现 新 资源 ， 这 几乎 与 你 在 Web 应 用 程 
序 中 通过 点 击 从 一 个 页 面 到 另 一 个 页 面 的 链接 来 发 现 新 页 面 的 方式 相同 。 理 想 情 况 下 ， 客 户 
端 可 以 输入 一 个 API， 而 不 需要 任何 有 关 其 中 的 资源 的 信息 ， 就 可 以 简单 地 通过 超 媒体 链接 来 
了 解 它 们 。 但 是 ， 与 HTML 和 XML 不 同 ， 通 常用 于 API 中 资源 表示 的 JSON 格 式 没 有 定义 包含 
链接 的 标准 方式 ， 因 此 你 不 得 不 使 用 自 定义 结构 ， 或 者 类 似 JSON-API，HAL ，JSON-LD 这 
样 的 试图 解决 这 种 差距 的 JSON 扩 展 之 一 。 


S ILAPI Blueprint 
为 了 让 你 体验 开发 API 所 涉及 的 内 容 ， 我 将 在 Microblog 添 加 API。 我 不 会 实现 所 有 的 API， 只 
会 实现 与 用 户 相关 的 所 有 功能 ， 并 将 其 他 资源 (如 用 户 动态 ) 的 实现 留 给 读者 作为 练习 。 


为 了 保持 组 织 有 序 ， 并 遵循 我 在 第 十 五 章 中 描述 的 结构 ， 我 将 创建 一 个 包含 所 有 API 路 由 的 新 
blueprint。 所 以 ， 让 我 们 从 创建 blueprint 所 在 的 目录 开始 : 


(venv) $ mkdir app/api 


在 blueprint 的 _init .py 文件 中 创建 blueprint 对 象 ， 这 与 应 用 程序 中 的 其 他 blueprint 类 似 : 
app/api/__init__.py : API blueprint 构造 器 。 
from flask import Blueprint 


bp = Blueprint('api', __name_) 


from app.api import users, errors, tokens 


你 可 能 会 记得 有 时 需要 将 导入 移动 到 底部 以 避免 循环 依赖 错误 。 这 就 是 为 什 
么 app/api/users.py，app/api/errors.py 和 app/api/tokens.py 模 块 (我 还 没有 写 ) 在 blueprint 创 
建 之 后 导入 的 原因 。 


API 的 主要 内 容 将 存储 在 app/api/users.py 模 块 中 。 下 表 总 结 了 我 要 实现 的 路 由 : 


HTTP 方法 资源 URL 注释 
GET /api/users/ 返回 一 个 用 户 
GET /api/users 返回 所 有 用 户 的 集合 
GET /api/users//followers 返回 某 个 用 户 的 粉丝 集合 
GET /api/users//followed 返回 某 个 用 户 关 注 的 用 户 集合 
POST /api/users 注册 一 个 新 用 户 


PUT /api/users/ 修改 某 个 用 户 


现在 我 要 创建 一 个 模块 的 框架 ， 其 中 使 用 占 位 符 来 暂时 填充 所 有 的 路 由 : 
app/api/users.py : 用 户 API 资 源 占 位 符 。 


from app.api import bp 
@bp.route('/users/<int:id>', methods=['GET']) 
def get_user(id): 
pass 
@bp.route('/users', methods=['GET']) 
def get_users(): 
pass 
@bp.route('/users/<int:id>/followers', methods=['GET']) 
def get_followers(id): 
pass 
@bp.route('/users/<int:id>/followed', methods=['GET']) 
def get_followed(id): 
pass 
@bp.route('/users', methods=['POST']) 
def create_user(): 
pass 
@bp.route('/users/<int:id>', methods=['PUT']) 


def update_user(id): 
pass 


app/api/errors.py 模 块 将 定义 一 些 处 理 错误 响应 的 辅助 函数 。 但 现在 ， 我 使 用 占 位 符 ， 并 将 在 
之 后 填充 内 容 : 
app/api/errors.py : 错误 处 理 占 位 符 。 


def bad_request(): 
pass 


app/api/tokens.py 是 将 要 定义 认证 子 系统 的 模块 。 它 将 为 非 Web 浏 览 器 登录 的 客户 端 提供 另 
一 种 方式 。 现 在 ， 我 也 使 用 占 位 符 来 处 理 该 模块 : 
app/api/tokens.py: Token 处 理 占 位 符 。 


def get_token(): 
pass 


def revoke_token(): 
pass 


新 的 API blueprint 需 要 在 应 用 工厂 函数 中 注册 : 


app/__init__.py : 应 用 中 注册 API blueprint ° 


# ..， 


def create_app(config_class=Config): 
app = Flask(__name_ ) 


# ... 


from app.api import bp as api_bp 
app.register_blueprint(api_bp, url_prefix='/api') 


# ... 


将 用 户 表示 为 JSON 对 象 


实施 API 时 要 考虑 的 第 一 个 方面 是 决定 其 资源 表示 形式 。 我 要 实现 一 个 用 户 类 型 的 API， 因 此 
我 需要 决定 的 是 用 户 资源 的 表示 形式 。 经 过 一 番 头 脑 风暴 ， 得 出 了 以 下 JSON 表 示 形 式 : 
{ 
"id": 123, 
"username": "susan", 
"password": "my-password", 
"email": "susan@example.com", 
"last_seen": "2017-10-20T15:04:27Z", 
"about_me": "Hello, my name is Susan!", 
"pyost_count": 7, 
"follower_count": 35, 
"followed_count": 21, 
"links": { 
"self": "/api/users/123", 
"followers": "/api/users/123/followers", 
"followed": "/api/users/123/followed", 
"avatar": "https://www.gravatar.com/avatar/..." 
} 
} 


许多 字段 直接 来 自用 户 数 据 库 模 型 。 password 字段 的 特殊 之 处 在 于 ， 它 仅 在 注册 新 用 户 时 才 
会 使 用 。 回顾 第 五 章 ， 用 户 密码 不 存储 在 数据 库 中 ， 只 存储 一 个 散 列 字 符 囊 ， 所 以 密码 永远 
不 会 被 返回 。 email 字段 也 被 专门 处 理 ， 因 为 我 不 想 公 开 用 户 的 电子 邮件 地 址 。 只 有 当 用 户 
请 求 自己 的 条 目 时 ， 才 会 返回 email 字段 ， 但 是 当 他 们 检索 其 他 用 户 的 条 目 时 不 会 返 

回 。 post_count ， follower_count 和 followed_count 字段 是 "虚拟 "字段 ， 它 们 在 数据 库 字 上 段 
中 不 存在 ， 提 供给 客户 端 是 为 了 方便 。 这 是 一 个 很 好 的 例子 ， 它 演示 了 资源 表示 不 需要 和 服 
务 器 中 资源 的 实际 定义 一 致 。 

请 注意 _links 部 分 ， 它 实现 了 超 媒 体 要 求 。 定义 的 链接 包括 指向 当前 资源 的 链接 ， 用 户 的 粉 
丝 列表 链接 ， 用 户 关注 的 用 户 列表 链接 ， 最 后 是 指向 用 户 。 将来， 如 果 我 决 
定向 这 个 API 添 加 用 户 动 态 ， 那 么 用 户 的 动态 列表 链接 也 应 包含 在 这 里 。 


JSON 格 式 的 一 个 好 处 是 ， 它 总 是 转换 为 Python 字典 或 列表 的 表示 形式 。 Python 标准 库 中 
的 json 包 负 责 Python 数据 结构 和 JSON 之 间 的 转换 。 因 此 ， 为 了 生成 这 些 表示 ， 我 将 
在 User 模型 中 添加 一 个 名 为 to_dict() 的 方法 ， 该 方法 返回 一 个 Python 字典 : 


app/models.py : User 模 型 转换 成 表示 。 


from flask import url_for 
# ..， 


class User(UserMixin, db.Model): 
# i... 


def to_dict(self, include_email=False): 
data = { 

‘id': self.id, 

"username': self.username, 

‘last_seen': self.last_seen.isoformat() + 'Z', 

‘about_me': self.about_me, 

"post_count': self.posts.count(), 

'follower_count': self.followers.count(), 

"followed_count': self.followed.count(), 

'_links': { 
'self': url_for('api.get_user', id=self.id), 
'followers': url_for('api.get_followers', id=self.id), 
'followed': url_for('api.get_followed', id=self.id), 
'avatar': self.avatar (128) 


} 


if include_email: 
data['email'] = self.email 
return data 


该 方法 一 目 了 然 ， 只 是 简单 地 生成 并 返回 用 户 表 示 的 字典 。 正 如 我 上 面 提 到 的 那 
E> email 字段 需要 特殊 处 理 ， 因 为 我 只 想 在 用 户 请 求 自己 的 数据 时 才 包 含 电子 邮件 。 所 以 
我 使 用 include_email 标志 来 确定 该 字段 是 否 包含 在 表示 中 。 


注意 一 下 last_seen 字段 的 生成 。 对 于 日 期 和 时 间 字 段 ， 我 将 使 用 ISO 8601 格 式 ，Python 
的 datetime 对 象 可 以 通过 isoformat() 方法 生成 这 样 格式 的 字符 串 。 但 是 因为 我 使 用 

的 datetime 对 象 的 时 区 是 UTC， 且 但 没有 在 其 状态 中 记录 时 区 ， 所 以 我 需要 在 末尾 添加 Z ， 
即 ISO 8601 的 UTC 时 区 代码 。 


最 后 ， 看 看 我 如 何 实现 超 媒体 链接 。 对 于 指向 应 用 其 他 路 由 的 三 个 链接 ， 我 使 

用 url_for() 生成 URL (目前 指向 我 在 app/ap1users.py 中 定义 的 占 位 符 视图 函数 ) 。 头像 链 
接 是 特殊 的 ， 因 为 它 是 应 用 外 部 的 Gravatar URL。 对 于 这 个 链接 ， 我 使 用 了 与 泻 业 网 页 中 的 
头像 的 相同 avatar() 方法 。 


to_dict() 方法 将 用 户 对 象 转换 为 Python 表示 ， 以 后 会 被 转换 为 JSON 。 我 还 需要 其 反 向 处 
理 的 方法 ， 即 客户 端 在 请 求 中 传递 用 户 表 示 ， 服 务 器 需要 解析 并 将 其 转换 为 User 对 象 。 以 
下 是 实现 从 Python 字典 到 user 对 象 转换 的 from dict() 方法 : 


app/models.py : 表示 转换 成 User 模 型 。 


class User(UserMixin, db.Model): 
# i... 


def from_dict(self, data, new_user=False): 
for field in ['username', ‘email', 'about_me']: 
if field in data: 
setattr(self, field, data[field]) 
if new_user and 'password' in data: 
self.set_password(data['password' ] ) 


本 处 我 决定 使 用 循环 来 导入 客户 端 可 以 设置 的 任何 字段 ， 
BP username ， email 和 about_me ° 对 于 每 个 字段 ， 我 检查 它 是 否 存在 于 data 参数 中 ， 如 
果 存 在 ， 我 使 用 Python 的 setattr() 在 对 象 的 相应 属性 中 设置 新 值 。 


password POER A ， 因 为 它 不 是 对 象 中 的 字段 。 new_user 参数 确定 了 这 是 否 是 新 的 
用 户 注 册 ， 这 意味 着 data PLS password 。 要 在 用 户 模型 中 设置 密码 ， 需 要 调 
用 set_password() 方法 来 创建 密码 哈 希 。 


表示 用 户 集合 


除了 使 用 单个 资源 表示 形式 外 ， 此 API 还 需要 一 组 用 户 的 表示 。 例如 客户 请 求 用 户 或 粉丝 列表 
时 使 用 的 格式 。 以 下 是 一 组 用 户 的 表示 : 


"items": [ 
{ ... user resource ... }, 
f ... user resource ... }, 


"page": 1, 
"per_page": 10, 
"total_pages": 20, 
"total_items": 195 
"_links": { 
"self": "http://localhost :5000/api/users?page=1", 


"next": "http://localhost :5000/api/users?page=2", 
"prev": null 


在 这 个 表示 中 ， items 是 用 户 资 源 的 列表 ， 每 个 用 户 ee ° _meta 部 分 
包含 集合 的 元 数据 ， 客 户 端 在 向 用 户 演 染 分 页 控件 时 就 会 _links 部 分 定义 了 相关 链 
接 ， 包 括 集 合 本 身 的 链接 以 及 上 一 页 和 下 一 页 链接 ， 也 外 oe mt] REIT DH © 
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他 资源 来 说 是 一 致 的 ， 所 以 我 将 以 通用 的 方式 实现 它 ， 以 便 适 用 于 其 他 模型 。 可 以 回顾 第 十 
六 章 ， 就 会 发 现 我 目前 的 情况 与 全 文 索引 类 似 ， 都 是 实现 一 个 功能 ， 还 要 让 它 可 以 应 用 于 任 
何 模型 。 对 于 全 文 索引 ， 我 使 用 的 解决 方案 是 实现 一 个 searchablemixin 类 ， 任 何 需要 全 文 索 
引 的 模型 都 可 以 从 中 继承 。 我 会 故 技 重 施 ， 实 现 一 个 新 的 mixin 类 ， 我 命名 


为 PaginatedAPIMixin 


app/models.py : 分 页 表示 mixin 类 。 


class PaginatedAPIMixin(object): 
@staticmethod 
def to_collection_dict(query, page, per_page, endpoint, **kwargs): 
resources = query.paginate(page, per_page, False) 


data = { 
‘items': [item.to_dict() for item in resources.items], 
'meta': { 
"page': page, 


"per_page': per_page, 
"total_pages': resources.pages, 
"total_items': resources.total 


}, 
'_links': { 
"self': url_for(endpoint, page=page, per_page=per_page, 
**kwargs), 
next ': url_for(endpoint, page=page + 1, per_page=per_page, 
**kwargs) if resources.has_next else None, 
"prev': url_for(endpoint, page=page - 1, per_page=per_page, 
**kwargs) if resources.has_prev else None 


} 

} 

return data 
to_collection_dict() 方法 产 生 一 个 带 有 用 户 集 合 表示 的 字典 ， 包 
括 items ° _meta 和 _links 部 分 你 可 能 需要 仔细 检查 该 方法 以 了 解 其 工作 原理 。 前 三 个 
参数 是 Flask-SQLAIchemy 查 询 对 象 ， 页 码 和 每 页 数据 数量 。 这 些 是 决定 要 返回 的 条 目 是 什么 
的 参数 。 该 实现 使 用 查询 对 象 的 paginate() 方法 来 获取 该 页 的 条 目 ， 就 像 我 对 主页 ， 发 现 页 
和 个 人 主页 中 的 用 户 动态 所 做 的 一 样 。 


复杂 的 部 分 是 生成 链接 ， 其 中 包括 自 引 用 以 及 指向 下 一 页 和 上 一 页 的 链接 。 我 想 让 这 个 函数 
具有 通用 性 ， 所 以 我 不 能 使 用 类 似 url for('api.get_users'，id=id，page=page) 这 样 的 代码 来 
生成 自 链接 ( 译 者 注 : 因为 这 样 就 固定 成 用 户 资 源 专 用 了 ) 。 url_for() 的 参数 将 取决 于 特 
定 的 资源 集合 ， 所 以 我 将 依赖 于 调用 者 在 endpoint 参数 中 传递 的 值 ， 来 确定 需要 发 送 

到 url_for() 的 视图 函数 。 由 于 许多 路 由 都 需要 参数 2 我 还 需要 在 kwargs 中 捕获 更 多 关键 字 
参数 ， 并 将 它们 传递 给 url _for() ° page 和 per_page 查询 字符 串 参 数 是 明确 给 出 的 ， 因 为 
它们 控制 所 有 API 路 由 的 分 页 。 


这 个 mixin 类 需要 作为 父 类 添加 到 User 模 型 中 : 


app/models.py : 添加 PaginatedAPIMixin 到 User 模 型 中 。 


class User(PaginatedAPIMixin, UserMixin, db.Model): 
# i... 


将 集合 转换 成 jsSon 表 示 ， 不 需要 反 向 操作 ， 因 为 我 不 需要 客户 端 发 送 用 户 列表 到 服务 器 。 


错误 处 理 


我 在 第 七 章 中 定义 的 错误 页 面 仅 适用 于 使 用 Web 浏 览 器 的 用 户 。 当 一 个 API 需 要 返回 一 个 错误 
时 ， 它 需要 是 一 个 “机 器 友好 "的 错误 类 型 ， 以 便 客 户 端 可 以 轻松 解释 这 些 错误 。 因此 ， 我 同 
样 设计 错误 的 表示 为 一 个 JSON 。 以 下 是 我 要 使 用 的 基本 结构 


{ 
"error": "short error description", 
"message": "error message (optional)" 
} 
了 错误 的 有 效 载 荷 之 外 ， 我 还 会 使 用 HTTP 协 议 的 状态 代码 来 指示 常见 错误 的 类 型 。 为 了 帮 


e l ERa » RAE app/api/errors.py F 5A error_response() 函数 : 


app/api/errors.py : 错误 响应 。 


from flask import jsonify 
from werkzeug.http import HTTP_STATUS_CODES 
def error_response(status_code, message=None): 
payload = {'error': HTTP_STATUS_CODES.get(status_code, 'Unknown error')} 
if message: 
payload['message'] = message 
response = jsonify(payload) 
response.status_code = status_code 
return response 


该 函数 使 用 来 自 Werkzeug (Flask 的 核心 依赖 项 ) 的 HTTP_STATUS_CoDES 字典 ， 它 为 每 个 
HTTP 状 态 代码 提供 一 个 简短 的 描述 性 名 称 。 我 在 错误 表示 中 使 用 这 些 名 称 作 为 error 字段 
的 值 ， 所 以 我 只 需要 操心 数字 状态 码 和 可 选 的 长 描述 。 jsonify() 函数 返回 一 个 默认 状态 码 
为 200 的 Flask Response 对 象 ， 因 此 在 创建 响应 之 后 ， 我 将 状态 码 设 置 为 对 应 的 错误 代码 。 


API 将 返回 的 最 常见 错误 将 是 代码 400， 代 表 了 "错误 的 请 求 "这 是 客户 端 发 送 请 求 中 包含 无 
效 数据 的 错误 。 为 了 更 容易 产生 这 个 错误 ， 我 将 为 它 添加 一 个 专用 函数 ， 只 需 传 入 长 的 描述 
性 消 息 作 为 参数 就 可 以 调用 9 下 面 是 我 之 前 添加 的 bad_request() 占 位 符 : 
app/api/errors.py : 错误 请 求 的 响应 。 

ere 


def bad_request(message): 
return error_response(400, message) 


用 户 资 源 Endpoint 
必需 的 用 户 JSON 表 示 的 支持 已 完成 ， 因 此 我 已 准备 好 开始 对 API endpoint 进 行 编码 了 。 


检索 单个 用 户 


让 我 们 就 从 使 用 给 定 的 id 来 检索 指定 用 户 开 始 吧 : 


app/api/users.py : 返回 一 个 用 户 。 
from flask import jsonify 
from app.models import User 
@bp.route('/users/<int:id>', methods=['GET']) 


def get_user(id): 
return jsonify(User.query.get_or_404(id).to_dict()) 


视图 函数 接收 被 请 求 用 户 的 id 作为 URL 中 的 动态 参数 。 查询 对 象 的 get_or_404() 方法 是 以 
前 见 过 的 get) 方法 的 一 个 非常 有 用 的 变 体 ， 如 果 用 户 存 在 ， 它 返回 给 定 id 的 对 象 ， 当 id 不 
存在 时 ， 它 会 中 止 请 求 并 向 客户 端 返回 一 个 404 错 误 ， 而 不 是 返回 None © 

get_or_404() 比 get() 更 有 优势 ， 它 不 需要 检查 查询 结果 ， 简 化 了 视图 函数 中 的 逻辑 。 

我 添加 到 User 的 to_dict() 方法 用 于 生成 用 户 资 源 表 示 的 字典 ， 然 后 Flask 的 jsonify() 函数 
将 该 字典 转换 为 JSON 格 式 的 响应 以 返回 给 客户 端 。 


如 果 你 想 查 看 第 一 条 API 路 由 的 工作 原理 ， 请 启动 服务 器 ， 然 后 在 浏览 器 的 地 址 栏 中 输入 以 下 
URL : 


http://localhost :5000/api/users/1 
浏览 器 会 以 JSON 格 式 显 示 第 一 个 用 户 。 也 尝试 使 用 大 一 些 的 id 值 来 查看 SQLAIchemy 查 询 


对 象 的 get_or_404() 方法 如 何 触 发 404 错 误 (我 将 在 稍 后 向 你 演示 如 何 扩展 错误 处 理 ， 以 便 
返回 这 些 错误 JSON 格 式 ) 。 


为 了 测试 这 条 新 路 由 ， 我 将 安装 HTTPie， 这 是 一 个 用 Python 编写 的 命令 行 HTTP 客 户 端 ， 可 
以 轻松 发 送 API 请 求 : 


(venv) $ pip install httpie 


我 现在 可 以 请 求 id 为 1 的 用 户 (可 能 是 你 自己 ) ， 命 令 如 下 : 


(venv) $ http GET http://localhost:5000/api/users/1 
HTTP/1.0 200 OK 

Content-Length: 457 

Content-Type: application/json 

Date: Mon, 27 Nov 2017 20:19:01 GMT 

Server: Werkzeug/0.12.2 Python/3.6.3 


{ 
SINKS 
"avatar": "https://www.gravatar.com/avatar/993c...2724?d=identicon&s=128", 
"followed": "/api/users/1/followed", 
"followers": "/api/users/1/followers", 
"self": "/api/users/1" 
}, 
"about_me": "Hello! I'm the author of the Flask Mega-Tutorial.", 
"followed_count": 0, 
"follower_count": 1, 
"id": “ily 
"last_seen": "2017-11-26T07:40:52.942865Z", 
"post_count": 10, 
"username": "miguel" 
} 


检索 用 户 集 合 
要 返回 所 有 用 户 的 集合 我 现在 可 以 依靠 PaginatedAPIMixin 的 to_collection_dict() 方法 : 


app/api/users.py : 返回 所 有 用 户 的 集合 。 


from flask import request 


@bp.route('/users', methods=['GET']) 
def get_users(): 
page = request.args.get('page', 1, type=int) 
per_page = min(request.args.get('per_page', 10, type=int), 100) 
data = User.to_collection_dict(User.query, page, per_page, ‘api.get_users') 
return jsonify(data) 


对 于 这 个 实现 ， 我 首先 从 请 求 的 查询 字符 串 中 提取 page 和 per_page ， 如 果 它 们 没有 被 定 
义 ， 则 分 别 使 用 默认 和 值 1 和 10。 per_page 具有 额外 的 逻辑 ， 以 100 为 上 限 。 给 客户 端 控件 请 
求 太 大 的 页 面 并 不 是 一 个 好 主意 ， 因 为 这 可 能 会 导致 服务 器 的 性 能 问题 。 然 

后 page 和 per_page 以 及 query 对 象 〈 在 本 例 中 ， 该 查询 只 是 User.query ， 是 返回 所 有 用 户 
的 最 通用 的 查询 ) 参数 被 传递 给 to_collection_query() 方法 。 最 后 一 个 参数 

是 api.get_users ， 这 是 我 在 表示 中 使 用 的 三 个 链接 所 需 的 endpoint 名 称 i 


要 使 用 HTTPie 测 试 此 endpoint， 请 使 用 以 下 命令 : 


(venv) $ http GET http://localhost:5000/api/users 


接 下 来 的 两 个 endpoint 是 返回 粉丝 集合 和 关注 用 户 集合 。 与 上面 的 非常 相似 : 


app/api/users.py : 返回 粉丝 列表 和 关注 用 户 列表 。 


@bp.route('/users/<int:id>/followers', methods=['GET']) 

def get_followers(id): 
user = User.query.get_or_404(id) 
page = request.args.get('page', 1, type=int) 
per_page = min(request.args.get('per_page', 10, type=int), 100) 
data = User.to_collection_dict(user.followers, page, per_page, 

"api.get_followers', id=id) 

return jsonify(data) 


@bp.route('/users/<int:id>/followed', methods=['GET']) 

def get_followed(id): 
user = User.query.get_or_404(id) 
page = request.args.get('page', 1, type=int) 
per_page = min(request.args.get('per_page', 10, type=int), 100) 
data = User.to_collection_dict(user.followed, page, per_page, 

"api.get_followed', id=id) 

return jsonify(data) 


由 于 这 两 条 路 由 是 特定 于 用 户 的 ， 因 此 它们 具有 id 动态 参数 。 id 用 于 从 数据 库 中 获取 用 
户 ， 然 后 将 user.followers 和 user.followed 关系 查询 提供 给 to_collection_dict() ? 所 以 希 
望 现在 你 可 以 看 到 ， 花 费 一 点 点 额外 的 时 间 ， 并 以 通用 的 方式 设计 该 方法 ， 对 于 获得 的 回报 
而 言 是 值得 的 。 to_collection_dict() 的 最 后 两 个 参数 是 endpoint 名 称 和 id > id 将 

在 kwargs 中 作为 一 个 额外 关键 字 参 数 ， 然 后 在 生成 链接 时 将 它 传递 给 url for() 。 


和 前 面 的 示例 类 似 ， 你 可 以 使 用 HTTPie 来 测试 这 两 个 路 由 ， 如 下 所 示 : 


(venv) $ http GET http://localhost :5000/api/users/1/followers 
(venv) $ http GET http://localhost :5000/api/users/1/followed 


由 于 超 媒 体 ， 你 不 需要 记 住 这 些 URL， 因 为 它们 包含 在 用 户 表 示 的 links 部 分 。 


注册 新 用 户 
/USers 路 由 的 post 请 求 将 用 于 注册 新 的 用 户 帐 户 。 你 可 以 在 下 面 看 到 这 条 路 由 的 实现 : 


app/api/users.py : 注册 新 用 户 。 


from flask import url_for 
from app import db 
from app.api.errors import bad_request 


@bp.route('/users', methods=['POST']) 
def create_user(): 
data = request.get_json() or {} 
if 'username' not in data or ‘'email' not in data or 'password' not in data: 
return bad_request('must include username, email and password fields') 
if User.query.filter_by(username=data['username']).first(): 
return bad_request('please use a different username' ) 
if User.query.filter_by(email=data['email']).first(): 
return bad_request('please use a different email address') 
user = User() 
user.from_dict(data, new_user=True) 
db.session.add(user) 
db.session.commit() 
response = jsonify(user.to_dict()) 
response.status_code = 201 
response.headers['Location'] = url_for('api.get_user', id=user.id) 
return response 


该 请 求 将 接受 请 求 主体 中 提供 的 来 自 客 户 端的 JSON 格 式 的 用 户 表示 。 Flask 

供 request.get_json() 方法 从 请 求 中 提取 JSON 并 将 其 作为 Python 结构 返回 。 如 果 在 请 求 中 
没有 找到 JSON 数 据 ， 该 方法 返回 None ， 所 以 我 可 以 使 用 表达 

式 request.get_json() or {} 确保 我 总 是 可 以 获得 一 个 字典 。 

在 我 可 以 使 用 这 些 数据 之 前 ， 我 需要 确保 我 已 经 掌握 了 所 有 信息 ， 因 此 我 首先 检查 是 否 包 含 
二 三 个 必 填 字段 ， username ， email 和 password 。 如 果 其 中 任何 一 个 缺失 ， 那么 我 使 

用 app/api/errors.py 模 块 中 的 bad_request() 辅助 函数 向 客户 端 返回 一 个 错误 。 除 此 之 外 ， 我 


还 需要 确保 username 和 email 字段 尚未 被 其 他 用 户 使 用 ， 因 此 我 尝试 使 用 获得 的 用 户 名 和 电 
子 邮件 从 数据 库 中 加 载 用 户 ， 如 果 返 回 了 有 效 的 用 户 ， 那 么 我 也 将 返回 错误 给 客户 端 。 


一 旦 通过 了 数据 验证 ， 我 可 以 轻松 创建 一 个 用 户 对 象 并 将 其 添加 到 数据 库 中 。 为 了 创建 用 
户 ， 我 依赖 User 模型 中 的 from_dict() 方法 ， new_user 参数 被 设置 为 True ， 所 以 它 也 接受 
通常 不 存在 于 用 户 表示 中 的 password 字段 。 


我 为 这 个 请 求 返回 的 响应 将 是 新 用 户 的 表示 ， 所 以 使 用 to _dict() 产生 它 的 有 效 载荷 。 创 建 
资源 的 post 请 求 的 响应 状态 代码 应 该 是 201， 即 创建 新 实体 时 使 用 的 代码 。 此 外，HTTP 协 
议 要 求 201 响 应 包含 一 个 值 为 新 资源 URL 的 Location 头 部 。 


下 面 你 可 以 看 到 如 何 通过 HTTPie 从 命令 行 注册 一 个 新 用 户 : 


(venv) $ http POST http://localhost:5000/api/users username=alice password=dog \ 
email=alice@example.com "about_me=Hello, my name is Alice!" 


编辑 用 户 
示例 API 中 使 用 的 最 后 一 个 endpoint 用 于 修改 已 存在 的 用 户 : 


app/api/users.py : 修改 用 户 。 


@bp.route('/users/<int:id>', methods=['PUT']) 
def update_user(id): 
user = User.query.get_or_404(id) 
data = request.get_json() or {} 
if 'username' in data and data['username'] != user.username and \ 
User.query.filter_by(username=data['username']).first(): 
return bad_request('please use a different username' ) 
if 'email' in data and data['email'] != user.email and \ 
User.query.filter_by(email=data['email']).first(): 
return bad_request('please use a different email address') 
user.from_dict(data, new_user=False) 
db.session.commit() 
return jsonify(user.to_dict()) 


一 个 请 求 到 来 ， 我 通过 URL 收 到 一 个 动态 的 用 户 id ， 所 以 我 可 以 加 载 指定 的 用 户 或 返回 404 
错误 (如 果 找 不 到 ) 。 就 像 注 册 新 用 户 一 样 ， 我 需要 验证 客户 端 提 供 的 username 和 email 字 
段 是 否 与 其 他 用 户 发 生 了 冲突 ， 但 在 这 种 情况 下 ， 验 证 有 点 棘手 。 首先 ， 这 些 字段 在 此 请 求 
中 是 可 选 的 ， 所 以 我 需要 检查 字段 是 否 存在 。 第 二 个 复杂 因素 是 客户 端 可 能 提供 与 目前 字段 
相同 的 值 ， 所 以 在 检查 用 户 名 或 电子 邮件 是 否 被 采用 之 前 ， 我 需要 确保 它们 与 当前 的 不 同 。 
如 果 任 何 验证 检查 失败 ， 那 么 我 会 像 之 前 一 样 返回 400 错 误 给 客户 端 。 


一 旦 数据 验证 通过 ， 我 可 以 使 用 user 模型 的 from dict() 方法 导入 客户 端 提供 的 所 有 数据 ， 
然后 将 更 改 提交 到 数据 库 。 该 请 求 的 响应 会 将 更 新 后 的 用 户 表示 返回 给 用 户 ， 并 使 用 软 认 的 
200 状 态 代 码 。 


以 下 是 一 个 示例 请 求 ， 它 用 HTTPie 编 辑 about_me 字段 : 


(venv) $ http PUT http://localhost:5000/api/users/2 "about_me=Hi, I am Miguel" 


API tA TE 


我 在 前 一 节 中 添加 的 APl endpoint 当 前 对 任何 客户 端 都 是 开放 的 。 显然 ， 执 行 这 些 操作 需要 
认证 用 户 才 安 全 ， 为 此 我 需要 添加 认证 和 授权 ， 简 称 *AuthN”" 和 “AuthZ”。 思路 是 ， 客 户 端 发 
送 的 请 求 提 供 了 某 种 标识 ， 以 便服 务 器 知道 客户 端 代表 的 是 哪 位 用 户 ， 并 且 可 以 验证 是 否 允 
许 该 用 户 执行 请 求 的 操作 。 


保护 这 些 APl endpoint 的 最 明显 的 方法 是 使 用 Flask-Login 中 的 @login_required 装饰 器 ， 但 是 
这 种 方法 存在 一 些 问 题 。 装饰 器 检测 到 未 通过 身份 验证 的 用 户 时 ， 会 将 用 户 重 定向 到 HTML 
登录 页 面 。 在 API 中 没有 HTML 或 登录 页 面 的 概念 ， 如 果 客 户 端 发 送 带 有 无 效 或 缺少 凭证 的 请 
求 ， 服 务 器 必须 拒绝 请 求 并 返回 401 状 态 码 。 服务 器 不 能 假定 API 客 户 端 是 Web 浏 览 器 ， 或 者 
它 可 以 处 理 重 定向 ， 或 者 它 可 以 泻 梁 和 处 理 HTML 登 录 表 单 。 当 API 客 户 端 收 到 401 状 态 码 
时 ， 它 知道 它 需 要 向 用 户 询问 赁 证， 但 是 它 是 如 何 实现 的 ， 服 务 器 不 需要 关心 。 


User 模 型 中 实现 Token 


对 于 API 身 份 验证 需求 ， 我 将 使 用 loken 身 份 验证 方案 。 当 客户 端 想 要 开始 与 API 交 互 时 ， 它 
需要 使 用 用 户 名 和 密码 进行 验证 ， 然 后 获得 一 个 临时 token。 只 要 token 有 效 ， 客 户 端 就 可 以 
发 送 附 带 token 的 API 请 求 以 通过 认证 。 一 旦 token 到 期 ， 需 要 请 求 新 的 token。 为 了 支持 用 户 
token， 我 将 扩展 User 模型 : 


app/models.py : 支持 用 户 token。 


import base64 
from datetime import datetime, timedelta 
import os 


class User(UserMixin, PaginatedAPIMixin, db.Model): 
# a’ 
token = db.Column(db.String(32), index=True, unique=True) 
token_expiration = db.Column(db.DateTime) 


# ... 


def get_token(self, expires_in=3600): 
now = datetime.utcnow() 
if self.token and self.token_expiration > now + timedelta(seconds=60): 

return self.token 

self.token = base64.b64encode(os.urandom(24)).decode('utf-8' ) 
self.token_expiration = now + timedelta(seconds=expires_in) 
db.session.add(self) 
return self.token 


def revoke_token(self): 
self.token_expiration = datetime.utcnow() - timedelta(seconds=1) 


@staticmethod 
def check_token(token): 
user = User.query.filter_by(token=token).first() 
if user is None or user.token_expiration < datetime.utcnow(): 
return None 
return user 


我 为 用 户 模型 添加 了 一 个 token 属性 ， 并 且 因为 我 需要 通过 它 搜 索 数据 库 ， 所 以 我 为 它 设置 
了 唯一 性 和 索引 。 我 还 添加 了 token_expiration 字段 ， 它 保存 token 过 期 的 日 期 和 时 间 。 
使 得 token 不 会 长 时 间 有 效 ， 以 免 成 为 安全 风险 。 


我 创建 了 三 种 方法 来 处 理 这 些 token 。 get_token() 方法 为 用 户 返回 一 个 token。 以 base64 编 
码 的 24 位 随机 字符 串 来 生成 这 个 token， 以 便 所 有 字符 都 处 于 可 读 字符 串 范围 内 。 在 创建 新 
token 之 前 ， 此 方法 会 检查 当前 分 配 的 token 在 到 期 之 前 是 否 至 少 还 剩 一 分 钟 ， 并 且 在 这 种 情况 
下 会 返回 现 有 的 token 。 


使 用 token 时 ， 有 一 个 策略 可 以 立即 使 token 失 效 总 是 一 件 好 事 ， 而 不 是 仅 依 赖 到 期 日 期 。 这 
是 一 个 经 常 被 忽视 的 安全 最 佳 实践 。 revoke_token() 方法 使 得 当前 分 配给 用 户 的 token 失 效 ， 
只 需 设 置 到 期 时 间 为 当前 时 间 的 前 一 秒 。 


check_token() 方法 是 一 个 静态 方法 ， 它 将 一 个 token 作 为 参数 传 入 并 返回 此 token 所 属 的 用 
户 。 如 果 token 无 效 或 过 期 ， 则 该 方法 返回 None 。 


由 于 我 对 数据 库 进行 了 更 改 ， 因 此 需要 生成 新 的 数据 库 迁 移 ， 然 后 使 用 它 升级 数据 库 : 


(venv) $ flask db migrate -m "user tokens" 
(venv) $ flask db upgrade 


# Token 74 R 


当 你 编写 一 个 API 时 ， 你 必须 考虑 到 你 的 客户 端 并 不 总 是 要 连接 到 Web 应 用 程序 的 Web 浏 览 
器 。 当 独立 客户 端 ( 如 智能 手机 APP) 甚至 是 基于 浏览 器 的 单 页 应 用 程序 访问 后 端 服务 时 ， 
API 展 示 力 量 的 机 会 就 米 了 。 当 这 些 专用 客户 端 需要 访问 API 服 务 时 ， 他 们 首先 需要 请 求 
token， 对 应 传统 Web 应 用 程序 中 登录 表单 的 部 分 


为 了 简化 使 用 token 认 证 时 客户 端 和 服务 器 之 间 的 交互 ， 我 将 使 用 名 为 Flask-HTTPAuth 的 
Flask 揪 件 。 Flask-HTTPAuth 可 以 使 用 pip 安 装 : 


(venv) $ pip install flask-httpauth 


Flask-HTTPAuth 支持 几 种 不 同 的 认证 机 制 ， 都 对 API 友 好 。 首先 ， 我 将 使 用 HTTPBasic 
Authentication， 该 机 制 要 求 客户 端 在 标准 的 Authorization 头 部 中 附带 用 户 赁 证 。 要 与 Flask- 
HTTPAuth 集 成 ， 应 用 需要 提供 两 个 函数 : e r ， AAM 
于 在 认证 失败 的 情况 下 返回 错误 响应 。 这 些 函 数 装饰 器 在 Flask-HTTPAuth 中 注册 ， 然 后 
在 认证 流程 中 根据 需要 由 插件 自动 调用 。 a 


app/api/auth.py : 基本 认证 支持 。 


from flask import g 

from flask_httpauth import HTTPBasicAuth 
from app.models import User 

from app.api.errors import error_response 


basic_auth = HTTPBasicAuth() 


@basic_auth.verify_password 
def verify_password(username, password): 
user = User.query.filter_by(username=username) .first() 
if user is None: 
return False 
g.current_user = user 
return user .check_password(password) 


@basic_auth.error_handler 
def basic_auth_error(): 
return error_response(401) 


Flask-HTTPAuth49 HTTPBasicAuth 类 实现 了 基本 的 认证 流程 。 这 两 个 必需 的 函数 分 别 通 


过 verify_password 和 error _handler 装饰 器 进行 注册 。 


验证 函数 接收 客户 端 提供 的 用 户 名 和 密码 ， 如 果 和 凭证 有 效 则 返回 true > SWRA False ° 
我 依赖 User 类 的 check_password() 方法 来 检查 密码 ， 它 在 Web 应 用 的 认证 过 程 中 ， 也 会 被 
Flask-Login 使 用 。 我 将 认证 用 户 保存 在 g.current_user 中 ， 以 便 我 可 以 从 API 视 图 函数 中 访 
问 它 。 


着 误 处 理 函 数 只 返回 由 9pp/api/errors.py 模 块 中 的 ~error_response() Se de es o 
401 错 误 在 HTTP 标 准 中 定义 为 “未 授权 ”错误 。 HTTP 客 户 端 知道 当 它 们 收 到 这 个 错误 时 ， 需 要 
重新 发 送 有 效 的 凭证 。 


现在 我 已 经 实现 了 基本 认证 的 支持 ， 因 此 我 可 以 添加 一 条 token 检 索 路 由 ， 以 便 客户 端 在 需要 
token 时 调用 : 


app/api/tokens.py : 生成 用 户 token ° 


from flask import jsonify, g 

from app import db 

from app.api import bp 

from app.api.auth import basic_auth 


@bp.route('/tokens', methods=['POST']) 
@basic_auth.login_required 
def get_token(): 
token = g.current_user.get_token() 
db.session.commit() 
return jsonify({'token': token}) 


这 个 视图 函数 使 用 了 _ HTTPBasicAuth 实例 中 的 @basic_auth. login_required 装饰 器 ， 它 将 指示 
Flask-HTTPAuth 验 证 身份 (通过 我 上 面 定 义 的 验证 函数 ) ， 并 且 仅 当 提 供 的 凭证 是 有 效 的 才 
BAT PF OMA BR BAILA BAN KMRMT A PRAY get_token() 方法 来 生成 token。 
数据 库 提 交 在 生成 token 后 发 出 ， 以 确保 token 及 其 到 期 时 间 被 写 回 到 数据 库 。 


如 果 你 尝试 直接 向 token API 路 由 发 送 POST 请 求 ， 则 会 发 生 以 下 情况 


(venv) $ http POST http://localhost:5000/api/tokens 
HTTP/1.0 401 UNAUTHORIZED 

Content-Length: 30 

Content-Type: application/json 

Date: Mon, 27 Nov 2017 20:01:00 GMT 

Server: Werkzeug/0.12.2 Python/3.6.3 

Www-Authenticate: Basic realm="Authentication Required" 


{ 
} 


"error": "Unauthorized" 


HTTP 响 应 包括 401 状 态 码 和 我 在 basic_auth_error() 函数 中 定义 的 错误 负载 。 下 面 请 求 带 上 
了 基本 认证 需要 的 凭证 


(venv) $ http --auth <username>:<password> POST http://localhost :5000/api/tokens 
HTTP/1.0 200 OK 

Content-Length: 50 

Content-Type: application/json 

Date: Mon, 27 Nov 2017 20:01:22 GMT 

Server: Werkzeug/0.12.2 Python/3.6.3 


"token": "pCiNu9wwyNt8VCjitrwilFdFI276AcbS" 


现在 状态 码 是 200， 这 是 成 功 请 求 的 代码 ， 并 且 有 效 载 荷包 括 用 户 的 token。 请 注意 ， 当 你 发 
送 这 个 请 求 时 ， 你 需要 用 你 自己 的 凭证 来 替换 <username>:<password> ° 用 户 名 和 密码 需要 以 
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使 用 Token 机 制 保 护 API 路 由 


客户 端 现在 可 以 请 求 一 个 token 来 和 API endpoint 一 起 使 用 ， 所 以 剩 下 的 就 是 向 这 些 endpoint 
添加 token 验 证 。 Flask-HTTPAuth 也 可 以 为 我 处 理 的 这 些 事情 。 我 需要 创建 基 
于 HTTPTokenAuth 类 的 第 二 个 身份 验证 实例 ， 并 提供 token 验 证 回调 : 


app/api/auth.py. Token 认 证 支持 。 


# i... 
from flask_httpauth import HTTPTokenAuth 


# wn. 
token_auth = HTTPTokenAuth() 


# ... 


@token_auth.verify_token 

def verify_token(token): 
g.current_user = User.check_token(token) if token else None 
return g.current_user is not None 


@token_auth.error_handler 
def token_auth_error(): 
return error_response(401) 


使 用 token 认 证 时 ，Flask-HTTPAuth 使 用 的 是 verify_token 装饰 器 注册 验证 函数 ， 除 此 之 
外 ，token 认 证 的 工作 方式 与 基本 认证 相同 。 我 的 token 验 证 函数 使 用 User.check_token() ian 
定位 token 所 属 的 用 户 。 该 函数 还 通过 将 当前 用 户 设 置 为 none 来 处 理 缺 失 token 的 情况 。 
值 是 True 还 是 False ， 决 定 了 Flask-HTTPAuth 是 否 允 许 视图 函数 的 运行 。 


w 


为 了 使 用 token 保 护 API 路 由 ， 需 要 添加 @token_auth.login_required 装饰 器 


app/api/users.py : 使 用 token 认 证 保护 用 户 路 由 。 


from app.api.auth import token_auth 


@bp.route('/users/<int:id>', methods=['GET']) 
@token_auth.login_required 
def get_user(id): 

uP soe 


@bp.route('/users', methods=['GET']) 
@token_auth.login_required 
def get_users(): 

# on, 


@bp.route('/users/<int:id>/followers', methods=['GET']) 
@token_auth.login_required 
def get_followers(id): 

# i... 


@bp.route('/users/<int:id>/followed', methods=['GET']) 
@token_auth.login_required 
def get_followed(id): 

# i... 


@bp.route('/users', methods=['POST']) 
def create_user(): 
# a’ 


@bp.route('/users/<int:id>', methods=['PUT']) 
@token_auth.login_required 
def update_user(id): 

# i... 


请 注意 ， 装 饰 器 被 添加 到 除 create_user() ZIP PTA APILA BRP > Lay WM > KP BR 
不 能 使 用 token 认 证 ， 因 为 用 户 都 不 存在 时 ， 更 不 会 有 token 了 。 


如 果 你 直接 对 上 面 列 出 的 受 token 保 护 的 endpoint 发 起 请 求 ， 则 会 得 到 一 个 401 错 误 。 为 了 成 
功 访问 ， 你 需要 添加 authorization 头 部 ， 其 值 是 请 求 /api/tokens 获 得 的 token 的 值 。Flask- 
HTTPAuth 期 望 的 是 "不 记名 "token， 但 是 它 没有 被 HTTPie 上 直接 支持 。 就 像 针对 基本 认证 ， 
HTTPie 提 供 了 --auth 选项 来 接受 用 户 名 和 密码 ， 但 是 token 的 头 部 则 需要 显 式 地 提供 了 。 下 
面 是 发 送 不 记名 token 的 格式 : 


(venv) $ http GET http://localhost:5000/api/users/1 \ 
"Authorization:Bearer pCiNu9wwyNt8VCjitrwilFdFI276AcbS" 


445 Token 
我 将 要 实现 的 最 后 一 个 token 相 关 功 能 是 token 撤 销 ， 如 下 所 示 : 
app/api/tokens.py : 撤销 token ° 


from app.api.auth import token_auth 


@bp.route('/tokens', methods=['DELETE']) 

@token_auth.login_required 

def revoke_token(): 
g.current_user.revoke_token() 
db.session. commit () 
return '', 204 


客户 端 可 以 向 /tokens URL 发 送 DELETE 请 求 ， 以 使 tpken 失 效 。 此 路 由 的 身份 验证 是 基于 
token 的 ， 事 实 上 ， 在 Authorization 头 部 中 发 送 的 token 就 是 需要 被 撤销 的 。 撤 销 使 用 

了 user 类 中 的 辅助 方法 ， 该 方法 重新 设置 token 过 期 日 期 来 实现 撤销 操作 。 之 后 提交 数据 库 
会 话 ， 以 确保 将 更 改写 入 数据 库 。 这 个 请 求 的 响应 没有 正文 ， 所 以 我 可 以 返回 一 个 空 字符 

串 。Return 语 名 中 的 第 二 个 值 设 置 状 态 代 码 为 204， 该 代码 用 于 成 功 请 求 却 没有 响应 主体 的 响 
应 。 


下 面 是 撤销 token 的 一 个 HTTPie 请 求 示例 : 


(venv) $ http DELETE http://localhost:5000/api/tokens \ 
Authorization:"Bearer pCiNu9wwyNt8VCjitrwWilFdFI276Acbs" 


API 友 好 的 错误 消息 


你 是 否 还 记得 ， 在 本 章 的 前 部 分 ， 当 我 要 求 你 用 ee 
求 时 发 生 了 什么 ?服务 器 返回 了 404 错 误 ， 但 是 这 个 错误 被 格式 化 为 标准 的 404 HTML 错 误 页 
面 。 在 API blueprint? $ APIT å ee eee 

HK 是 由 Flask 处 理 的 ， 处 理 这 些 错误 的 处 理 函 数 是 被 全 局 注册 到 应 用 中 的 ， 返 回 的 是 
HTML 。 


HTTP 协 议 支持 一 种 机 制 ， 通 过 该 机 制 ， 客 户 机 和 服务 器 可 以 就 响应 的 最 佳 格式 达成 一 致 ， 称 
为 内 容 协 商 。 客 户 端 需要 发 送 一 个 accept 头 部 ， 指 示 格 式 首选 项 。 然 后 ， 服 务 器 查看 自身 格 
式 列 表 并 使 用 匹配 客户 端 格 式 列表 中 的 最 佳 格式 进行 响应 。 


我 想 做 的 是 修改 全 局 应 用 的 错误 处 理 器 ， 使 它们 能 够 根据 客户 端的 格式 首选 项 对 返回 内 容 是 
使 用 HTML 还 是 JSON 进 行内 容 协 商 。 这 可 以 通过 使 用 Flask 的 request.accept_mimetypes 来 完 
成 : 


app/errors/handlers.py : 为 错误 响应 进行 内 容 协 商 。 


from flask import render_template, request 

from app import db 

from app.errors import bp 

from app.api.errors import error_response as api_error_response 


def wants_json_response(): 
return request.accept_mimetypes['application/json'] >= \ 
request.accept_mimetypes['text/html1' ] 


@bp.app_errorhandler (404) 
def not_found_error(error): 
if wants_json_response(): 
return api_error_response( 404) 
return render_template('errors/404.htm1'), 404 


@bp.app_errorhandler (500) 
def internal_error(error): 
db.session.rollback() 
if wants_json_response(): 
return api_error_response(500) 
return render_template('errors/500.htm1'), 500 


wants_json_response() 辅助 函数 比较 客户 端 对 JSON 和 HTML 格 式 的 偏好 程度 。 如 果 JSON 比 
HTML 高 ， 那 么 我 会 返回 一 个 JSON 响 应 。 否则 ， 我 会 返回 原始 的 基于 模板 的 HTML 响 应 。 对 
于 JSON 响 应 ， 我 将 使 用 从 API blueprint F $A error_response 辅助 函数 ， 但 在 这 里 我 要 将 其 
重 命名 为 api_error_response() ， 以 便 清楚 它 的 作用 和 来 历 。 


